Beneficiaries

A beneficiary is a saved recipient. Save someone’s details once, keep the externalAccountId Tanda returns, and pay them later by sending just that ID. In the API, beneficiaries are called external accounts, which is why the endpoints live under /api/b2b/external-accounts.

Use beneficiaries for anyone you pay more than once: staff, suppliers, agents or regular customers.

Save a beneficiary

Call Create beneficiary with type: "payout", the destination and the payout details. Check the details with Account resolver first.

{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "MoMo",
    "payoutMethod": {
      "accountName": "Grace Achieng",
      "accountNumber": "254712345678",
      "code": "mpesa"
    }
  }
}

{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Bank Account",
    "payoutMethod": {
      "accountName": "Kilimo Supplies Ltd",
      "accountNumber": "01100123456700",
      "code": "1243"
    }
  }
}

{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Paybill",
    "payoutMethod": {
      "accountName": "Kenya Power",
      "accountNumber": "ACC-778812",
      "businessNumber": "888880"
    }
  }
}

{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Till",
    "payoutMethod": {
      "accountName": "Mama Mboga Stores",
      "accountNumber": "123456"
    }
  }
}

Response

{
  "success": true,
  "message": "External account created successfully.",
  "data": { "id": "ea_9Xk2LmPq" }
}

Store data.id against the recipient in your system. That’s the externalAccountId.

You can also save a customer you charge often, with type: "deposit" and firstName, lastName and phoneNumber in payload. Pass the ID as externalAccountId on a mobile money charge.

Pay a beneficiary

curl -X POST https://api.tandapay.io/api/b2b/fiat/payout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "externalReference": "payout_5536",
    "externalAccountId": "ea_9Xk2LmPq"
  }'

Manage beneficiaries

To	Use
List all	List beneficiaries
Fetch one	Get beneficiary
Change details	Update beneficiary
Remove	Delete beneficiary

When a recipient changes their bank or number, update the existing beneficiary rather than creating a new one, and delete beneficiaries you no longer pay.

Get started

Accept payments

Send payouts

Webhooks

Go live

Save a beneficiary

Pay a beneficiary

Manage beneficiaries

​Save a beneficiary

​Pay a beneficiary

​Manage beneficiaries

Save a beneficiary

Pay a beneficiary

Manage beneficiaries