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

# API reference

> Conventions shared by every Tanda endpoint.

Every endpoint page has a playground. Paste a bearer token into the **Authorization** field to send requests; a token from sandbox keys keeps them in sandbox.

## Base URL

```bash theme={null}
https://api.tandapay.io
```

Sandbox and production share the base URL; your keys pick the environment. See [Environments](https://api.tandapay.io/guides/environments.md).

## Authentication

Every endpoint except [Generate bearer token](https://api.tandapay.io/api-reference/endpoint/generate-bearer-token.md) needs:

```bash theme={null}
Authorization: Bearer <token>
```

Generate bearer token takes your secret in an `api-key` header and your public key in the body. Tokens last one hour.

## Requests and responses

* Send JSON with `Content-Type: application/json`.
* Responses are JSON with a `success` boolean. Most put their payload in `data`.
* Currency is `KES` and country is `KE`.
* Amounts are in shillings: `1500` is KES 1,500.
* Phone numbers use `254XXXXXXXXX`, without the `+`. The one exception is [Get phone number operator](https://api.tandapay.io/api-reference/endpoint/get-phone-number-operator.md), which takes `+254XXXXXXXXX`.

## Idempotency

Checkout sessions, charges, payouts and refunds require an `externalReference` that you generate, unique to each transaction. Sending the same value again returns `409 DUPLICATE_EXTERNAL_REFERENCE` instead of creating a second transaction, so it's safe to resend a request that timed out. You can also use `externalReference` in place of `transactionId` with [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md).

## Asynchronous results

A `200` from a charge or payout means the request was accepted. The result arrives later by [webhook](https://api.tandapay.io/guides/webhooks/overview.md). Only `successful` means money moved.

## Errors

Failed requests return a `4xx` or `5xx` status with `success: false`, a human-readable `message` and, for most errors, an `errorCode` to branch on. See [API errors](https://api.tandapay.io/guides/errors/api-errors.md).

## Endpoints

| Group | Endpoints |
| :- | :- |
| Authentication | [Generate bearer token](https://api.tandapay.io/api-reference/endpoint/generate-bearer-token.md) |
| Account | [Get user](https://api.tandapay.io/api-reference/endpoint/get-user.md) |
| Checkout | [Create session](https://api.tandapay.io/api-reference/endpoint/create-checkout-session.md), [Get methods](https://api.tandapay.io/api-reference/endpoint/get-checkout-methods.md) |
| Collections | [Mobile money](https://api.tandapay.io/api-reference/endpoint/mobile-money-charge.md), [Bank transfer](https://api.tandapay.io/api-reference/endpoint/bank-transfer.md), [Validate OTP](https://api.tandapay.io/api-reference/endpoint/validate-otp.md), [Refund](https://api.tandapay.io/api-reference/endpoint/refund-deposit.md) |
| Payouts | [Create payout](https://api.tandapay.io/api-reference/endpoint/create-payout.md) |
| Beneficiaries | [Create](https://api.tandapay.io/api-reference/endpoint/create-beneficiary.md), [List](https://api.tandapay.io/api-reference/endpoint/list-beneficiaries.md), [Get](https://api.tandapay.io/api-reference/endpoint/get-beneficiary.md), [Update](https://api.tandapay.io/api-reference/endpoint/update-beneficiary.md), [Delete](https://api.tandapay.io/api-reference/endpoint/delete-beneficiary.md) |
| Transactions | [List](https://api.tandapay.io/api-reference/endpoint/list-transactions.md), [Get](https://api.tandapay.io/api-reference/endpoint/get-transaction.md) |
| Reference data | [Banks](https://api.tandapay.io/api-reference/endpoint/get-banks.md), [Mobile money providers](https://api.tandapay.io/api-reference/endpoint/get-mobile-money-providers.md), [Phone operator](https://api.tandapay.io/api-reference/endpoint/get-phone-number-operator.md), [Account resolver](https://api.tandapay.io/api-reference/endpoint/account-resolver.md), [Service status](https://api.tandapay.io/api-reference/endpoint/service-status.md) |
| Webhooks | [List deliveries](https://api.tandapay.io/api-reference/endpoint/list-webhook-deliveries.md), [Get delivery](https://api.tandapay.io/api-reference/endpoint/get-webhook-delivery.md), [Resend](https://api.tandapay.io/api-reference/endpoint/resend-webhook.md), [Simulate](https://api.tandapay.io/api-reference/endpoint/simulate-webhook.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.