Sending payouts

Every payout goes to Create payout:

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.

{
  "amount": 1000,
  "currency": "KES",
  "country": "KE",
  "destination": "MoMo",
  "externalReference": "payout_5531",
  "payoutMethod": {
    "accountName": "Grace Achieng",
    "accountNumber": "254712345678",
    "code": "mpesa"
  }
}

{
  "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.

{
  "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).

{
  "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.

{
  "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, send only the amount, your reference and the externalAccountId:

{
  "amount": 1000,
  "externalReference": "payout_5536",
  "externalAccountId": "ea_9Xk2LmPq"
}

Don’t send currency, country, destination or payoutMethod with an externalAccountId. The saved details are used.

Response

{
  "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 `chargeStatus`	`pending`, `successful`, `failed`
Get transaction `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, then retry with a new reference.
Insufficient wallet balance	Top up your wallet and retry.
Invalid bank code	Refresh the list from Get banks.
Recipient limit exceeded	Send a smaller amount or split it. M-PESA wallets have daily and balance limits.
Service unavailable	Check Service status 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.

Get started

Accept payments

Send payouts

Webhooks

Go live

Mobile money

Bank account

Paybill

Till

Saved beneficiary

Response

Checking status

When payouts fail

Good practice

​Mobile money

​Bank account

​Paybill

​Till

​Saved beneficiary

​Response

​Checking status

​When payouts fail

​Good practice

Mobile money

Bank account

Paybill

Till

Saved beneficiary

Response

Checking status

When payouts fail

Good practice