Skip to main content

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

DirectionMethodEndpoint
CollectM-Pesa STK pushPOST /v1/transactions/m-pesa/c2b/initiate
CollectAirtel MoneyPOST /v1/transactions/airtel/collect/initiate
CollectPesalink bank transferPOST /v1/transactions/pesalink/c2b/initiate
Pay outM-Pesa B2CPOST /v1/transactions/m-pesa/b2c/initiate
Pay outAirtel MoneyPOST /v1/transactions/airtel/payout/initiate
Pay outPochi la BiasharaPOST /v1/transactions/m-pesa/pochi/initiate
Pay outTillPOST /v1/transactions/m-pesa/till/initiate
Pay outPaybillPOST /v1/transactions/m-pesa/paybill/initiate
Pay outBank (PesaLink)POST /v1/pesalink/bank-transfer/verify then /complete
UndoReversePOST /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.

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)​

Float required

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.

Paying yourself is a settlement, not a payout

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"
}

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.

Path prefix

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.

  • 404 if the transaction isn't yours.
  • 422 if it isn't complete, 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 externalId to 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 externalId to see whether it was created.

The full list of destinationBankCode values is on the PesaLink bank codes page.