Direct payments & payouts
Beyond the hosted checkout, the API exposes direct endpoints for collecting from and paying out to M-Pesa and banks. All of them require a company Bearer token, and all of them return a transaction you can poll at GET /v1/transactions/{id}.
| Direction | Method | Endpoint |
|---|---|---|
| Collect | M-Pesa STK push | POST /v1/transactions/m-pesa/c2b/initiate |
| Collect | Airtel Money | POST /v1/transactions/airtel/collect/initiate |
| Collect | Pesalink bank transfer | POST /v1/transactions/pesalink/c2b/initiate |
| Pay out | M-Pesa B2C | POST /v1/transactions/m-pesa/b2c/initiate |
| Pay out | Airtel Money | POST /v1/transactions/airtel/payout/initiate |
| Pay out | Pochi la Biashara | POST /v1/transactions/m-pesa/pochi/initiate |
| Pay out | Till | POST /v1/transactions/m-pesa/till/initiate |
| Pay out | Paybill | POST /v1/transactions/m-pesa/paybill/initiate |
| Pay out | Bank (PesaLink) | POST /v1/pesalink/bank-transfer/verify then /complete |
| Undo | Reverse | POST /v1/transactions/{id}/reverse |
Outcomes arrive by webhook (see Webhook events) or by polling.
Collections (money in)
M-Pesa STK push
POST /v1/transactions/m-pesa/c2b/initiate
Sends the payment prompt straight to the customer's phone:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/transactions/m-pesa/c2b/initiate \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "0712345678",
"amount": 100,
"accountReference": "Account123",
"transactionDesc": "Top-up",
"externalId": "your-transaction-id"
}'
The customer enters their M-Pesa PIN on the prompt; the transaction completes (or fails/times out) shortly after. Use webhooks or poll the returned transaction id.
Airtel Money collection
POST /v1/transactions/airtel/collect/initiate
The Airtel Money equivalent of an STK push. The customer gets a USSD prompt and approves it with their Airtel Money PIN:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/transactions/airtel/collect/initiate \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "0733123456",
"amount": 100,
"accountReference": "Account123",
"transactionDesc": "Order #1042",
"externalId": "your-transaction-id"
}'
The transaction comes back pending. It moves to complete or failed when the customer answers, or when the prompt expires unanswered. You get a transaction.completed or transaction.failed webhook with type: "AIRTEL_COLLECTION", or you can poll the transaction id.
Pesalink bank transfer (C2B)
POST /v1/transactions/pesalink/c2b/initiate
Creates a pending bank transaction; it completes when the customer finishes the transfer from their own bank:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/transactions/pesalink/c2b/initiate \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"accountReference": "Account123",
"transactionDesc": "Invoice settlement",
"externalId": "your-transaction-id"
}'
Payouts (money out)
Payouts are funded from your company float. Each initiate call checks and reserves amount + fee from your float balance first; if it is insufficient you get a 400 with the available and required amounts. Fees follow the standard M-Pesa tariff for the amount.
These endpoints send money to third parties and go out the moment you call them. Moving your own float to an account you control goes through Settlements instead — the amount is held and an operator approves it first.
M-Pesa B2C (send to phone)
POST /v1/transactions/m-pesa/b2c/initiate
{
"amount": 100,
"phoneNumber": "0712345678",
"accountReference": "Account123",
"transactionDesc": "Withdrawal",
"externalId": "your-transaction-id"
}
Airtel Money payout (send to phone)
POST /v1/transactions/airtel/payout/initiate
{
"amount": 100,
"phoneNumber": "0733123456",
"accountReference": "Account123",
"transactionDesc": "Withdrawal",
"externalId": "your-transaction-id"
}
Paid from your Airtel float, which is separate from your M-Pesa float. The request fails with 400 if that float can't cover the amount plus Airtel's payout fee. The payout completes asynchronously: watch for the webhook (type: "AIRTEL_PAYOUT") or poll the transaction.
Pochi la Biashara
POST /v1/transactions/m-pesa/pochi/initiate
{
"amount": 100,
"pochiNumber": "0712345678",
"accountReference": "Account123",
"transactionDesc": "Payment to pochi"
}
Till (Buy Goods)
POST /v1/transactions/m-pesa/till/initiate
{
"amount": 100,
"tillNumber": "123456",
"accountReference": "Account123",
"transactionDesc": "Payment to till",
"initiatorPhoneNumber": "0712345678"
}
Paybill
POST /v1/transactions/m-pesa/paybill/initiate
{
"amount": 100,
"paybillNumber": "123456",
"accountNumber": "5551234",
"accountReference": "Account123",
"transactionDesc": "Payment to paybill",
"customerNumber": "0712345678"
}
PesaLink bank transfer (send to a bank account)
Pays out to any PesaLink-connected bank account. Unlike the M-Pesa payouts, this is a two-step flow so you can show the resolved account holder name to your user before any money moves.
These two endpoints live under /v1/pesalink, not /v1/transactions.
Step 1 — verify the beneficiary and prepare the transfer. This verifies the destination account with the receiving bank, reserves your float for amount + fee, and returns a transactionId for a pending transfer:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/pesalink/bank-transfer/verify \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"destinationBankCode": "40407000",
"destinationAccount": "7357060021",
"amount": 5000,
"narrative": "Supplier payment",
"reference": "INV-2024-001"
}'
{
"transactionId": "WDRPSLK1A2B3C4D5E6F7A8B9",
"accountHolderName": "John ****",
"amount": 5000,
"fee": 22,
"currency": "KES",
"beneficiaryAccount": "7357060021",
"beneficiaryBankCode": "40407000",
"status": "pending",
"message": "Beneficiary verified and transfer prepared. Confirm with the transactionId to complete."
}
If verification fails or your float is insufficient, this returns 400 and no transfer is created.
Step 2 — complete the transfer using the transactionId from step 1. On success the amount + fee is drawn down from your float:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/pesalink/bank-transfer/complete \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transactionId": "WDRPSLK1A2B3C4D5E6F7A8B9" }'
{
"message": "Bank transfer completed successfully",
"transaction": { /* transaction object, type BANK_TRANSFER */ }
}
404 if the transactionId isn't a pending transfer for your merchant; 422 if it's already settled or the receiving bank rejects it.
See PesaLink bank codes for the destinationBankCode values.
Reversing a transaction
Send the money of a completed M-Pesa deposit or payout back through Safaricom:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/transactions/{id}/reverse \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "amount": 500, "remarks": "Duplicate payment", "occasion": "Customer refund" }'
All body fields are optional. amount defaults to the full original amount and can't exceed it.
The response carries a reversal transaction in pending status. Safaricom only acknowledges the request at first; the reversal moves to complete or failed once Safaricom confirms, so poll GET /transactions/{id} on the returned transaction.
404if the transaction isn't yours.422if it isn'tcomplete, isn't a deposit or payout, is itself a reversal, or didn't go through M-Pesa. Airtel, Pesalink and card transactions can't be reversed this way yet.- A transaction that already has a reversal returns that reversal rather than sending the money back twice.
Tracking transactions
Every initiate endpoint responds with a transaction object. Fetch its latest state at any time:
curl https://sandbox.merchants.taifapay.africa/v1/transactions/{id} \
-H "Authorization: Bearer $ACCESS_TOKEN"
You can pass either the API's transaction id or your own externalId reference. Statuses move pending → complete or failed; payouts release their float reservation if they fail.
Idempotency and reconciliation
- Always set
externalIdto your own unique id for the operation. It is echoed back on transactions and webhooks, letting you match events to your records. - If an initiate call times out on your side, do not blindly retry — first look the transaction up by your
externalIdto see whether it was created.
PesaLink bank codes
The full list of destinationBankCode values is on the PesaLink bank codes page.