> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerocash.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Conventions, authentication, and error handling shared by every Zerocash endpoint.

Every endpoint page in this section is generated from the Zerocash OpenAPI specification and ships
with an interactive playground — fill in your token and run a live request from the page.

## Base URL

<CodeGroup>
  ```bash Base URL theme={null}
  https://api.zerocash.tech
  ```
</CodeGroup>

Sandbox and production share this host. Which environment you hit depends on the credentials
behind your bearer token. See [Environments](/guides/environments).

## Authentication

All endpoints except [Generate Bearer Token](/api-reference/endpoint/generate-bearer-token) expect a
bearer token:

```bash theme={null}
Authorization: Bearer YOUR_BEARER_TOKEN
```

The token endpoint itself authenticates differently — it takes your secret in an `api-key` header
and your public key in the body. Full walkthrough in [Authentication](/guides/authentication).

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Mint bearer tokens and read your account profile and configured webhook URLs.
  </Card>

  <Card title="Reference Data" icon="table-list">
    Countries, banks, branches, mobile money providers, operator lookup, account resolution,
    service uptime, and FX rates.
  </Card>

  <Card title="Charges" icon="arrow-down-to-line">
    Collect payments by mobile money, bank transfer, card, and OPay — plus OTP validation and
    refunds.
  </Card>

  <Card title="Payouts" icon="arrow-up-from-line">
    Disburse funds to mobile money and bank destinations, and manage saved external accounts.
  </Card>

  <Card title="Transactions" icon="receipt">
    List transactions and look one up by `transactionId` or your own `externalReference`.
  </Card>

  <Card title="Webhooks" icon="bell">
    Inspect delivery attempts, resend a webhook, and simulate events in the sandbox.
  </Card>
</CardGroup>

## Conventions

<AccordionGroup>
  <Accordion title="externalReference" icon="fingerprint">
    A unique ID you supply when creating a charge or payout. It is your reconciliation key, it
    protects you from duplicate transactions on retry, and it can be used in place of
    `transactionId` when fetching a transaction.
  </Accordion>

  <Accordion title="Amounts and currencies" icon="coins">
    `currency` is an ISO 4217 code (`KES`, `UGX`, `NGN`, `XOF`). `country` is an ISO 3166-1 alpha-2
    code (`KE`, `NG`). Amounts are expressed in the major unit of the currency.
  </Accordion>

  <Accordion title="Phone numbers" icon="phone">
    E.164 format **without** the leading plus — for example `254712345678`, not `+254712345678`.
  </Accordion>

  <Accordion title="Asynchronous settlement" icon="clock">
    A `200` on a charge or payout means accepted for processing. The final outcome arrives by
    webhook or by polling the transaction. Only a `successful` status means funds moved.
  </Accordion>

  <Accordion title="stepRequired" icon="list-check">
    Some charges pause for customer action. `otp` means collect a code and submit it to
    [Validate OTP](/api-reference/endpoint/validate-otp); `redirect` means send the customer to the
    returned `redirectUrl`; card charges may additionally require `pin` or `address_verification`
    via [Authorise Charge](/api-reference/endpoint/authorise-charge).
  </Accordion>
</AccordionGroup>

## Errors

Zerocash uses standard HTTP status codes. `4xx` and `5xx` responses carry a JSON body with an
`errorCode` and a human-readable `message`.

<CardGroup cols={2}>
  <Card title="API error codes" icon="triangle-exclamation" href="/guides/errors/api-errors">
    HTTP-level failures: authentication, validation, and rate limiting.
  </Card>

  <Card title="Transaction error codes" icon="circle-xmark" href="/guides/errors/transaction-error-codes">
    Why an individual charge or payout failed, and what to do about each case.
  </Card>
</CardGroup>