> ## 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.

# Sending payouts

> Request bodies for every payout destination, plus status and failure handling.

Every payout goes to [Create payout](https://api.tandapay.io/api-reference/endpoint/create-payout.md):

```bash theme={null}
POST https://api.tandapay.io/api/b2b/fiat/payout
```

These fields are the same for every destination:

| Field | Required | Notes |
| :- | :-: | :- |
| `amount` | Yes | KES, e.g. `1000`. |
| `currency` | Yes | `KES`. |
| `country` | Yes | `KE`. |
| `destination` | Yes | `MoMo`, `Bank Account`, `Paybill` or `Till`. |
| `externalReference` | Yes | Your unique ID for this payout. |
| `payoutMethod` | Yes | Recipient details; see each destination below. |

## Mobile money

Pays an M-PESA or Airtel Money wallet. `accountNumber` is the phone number without the `+`; `code` is the network.

```json M-PESA theme={null}
{
  "amount": 1000,
  "currency": "KES",
  "country": "KE",
  "destination": "MoMo",
  "externalReference": "payout_5531",
  "payoutMethod": {
    "accountName": "Grace Achieng",
    "accountNumber": "254712345678",
    "code": "mpesa"
  }
}
```

```json Airtel Money theme={null}
{
  "amount": 1000,
  "currency": "KES",
  "country": "KE",
  "destination": "MoMo",
  "externalReference": "payout_5532",
  "payoutMethod": {
    "accountName": "Grace Achieng",
    "accountNumber": "254733123456",
    "code": "airtel"
  }
}
```

## Bank account

Pays a Kenyan bank account. `code` is the bank code from [Get banks](https://api.tandapay.io/api-reference/endpoint/get-banks.md).

```json theme={null}
{
  "amount": 50000,
  "currency": "KES",
  "country": "KE",
  "destination": "Bank Account",
  "externalReference": "payout_5533",
  "payoutMethod": {
    "accountName": "Kilimo Supplies Ltd",
    "accountNumber": "01100123456700",
    "code": "1243"
  }
}
```

Bank payouts typically take between 1 and 24 hours, depending on the receiving bank.

## Paybill

Pays an M-PESA paybill. `businessNumber` is the paybill number; `accountNumber` is the account the payment is for (the "account number" a customer would type on their phone).

```json theme={null}
{
  "amount": 5000,
  "currency": "KES",
  "country": "KE",
  "destination": "Paybill",
  "externalReference": "payout_5534",
  "payoutMethod": {
    "accountName": "Kenya Power",
    "accountNumber": "ACC-778812",
    "businessNumber": "888880"
  }
}
```

## Till

Pays an M-PESA Buy Goods till. `accountNumber` is the till number. No `code` or `businessNumber`.

```json theme={null}
{
  "amount": 2500,
  "currency": "KES",
  "country": "KE",
  "destination": "Till",
  "externalReference": "payout_5535",
  "payoutMethod": {
    "accountName": "Mama Mboga Stores",
    "accountNumber": "123456"
  }
}
```

## Saved beneficiary

If you've saved the recipient as a [beneficiary](https://api.tandapay.io/guides/payouts/beneficiaries.md), send only the amount, your reference and the `externalAccountId`:

```json theme={null}
{
  "amount": 1000,
  "externalReference": "payout_5536",
  "externalAccountId": "ea_9Xk2LmPq"
}
```

> [!WARNING]
>
> Don't send `currency`, `country`, `destination` or `payoutMethod` with an `externalAccountId`. The saved details are used.

## Response

```json theme={null}
{
  "success": true,
  "message": "Withdrawal Request Accepted for Processing.",
  "transactionId": "pY7tR5eW3qA1sD9fG2hJ"
}
```

Accepted isn't paid. The outcome follows by webhook.

## Checking status

| Where | Values |
| :- | :- |
| Webhook `data.status` | `pending`, `successful`, `failed` |
| [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md) `chargeStatus` | `pending`, `successful`, `failed` |
| [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md) `status` | `PENDING`, `SUCCESSFUL`, `FAILED` |
| Transaction `type` | `withdrew` for payouts |

A successful payout includes `thirdPartyReference` (for example the M-PESA receipt). A failed payout's `payout_updated` webhook includes a `failureReason`.

## When payouts fail

| Reason | What to do |
| :- | :- |
| Recipient account not found | Check the details with [Account resolver](https://api.tandapay.io/api-reference/endpoint/account-resolver.md), then retry with a new reference. |
| Insufficient wallet balance | Top up your wallet and retry. |
| Invalid bank code | Refresh the list from [Get banks](https://api.tandapay.io/api-reference/endpoint/get-banks.md). |
| Recipient limit exceeded | Send a smaller amount or split it. M-PESA wallets have daily and balance limits. |
| Service unavailable | Check [Service status](https://api.tandapay.io/api-reference/endpoint/service-status.md) and retry later. |

## Good practice

* Resolve accounts before paying, especially for first-time recipients.
* On a timeout, retry with the **same** `externalReference`; a `409` means Tanda already has it, so check its status. Use a new reference only after a confirmed failure.
* Watch your success rate. A sudden drop usually points to a network outage or a bad batch of recipient details.


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