Overview
The Transactions API lets your company collect payments, send payouts and manage customer wallets through one REST API, and tells you what happened through signed webhooks.
| You want to | Use | Guide |
|---|---|---|
| Get paid without building a payment page | Hosted checkout and payment links | Hosted checkout |
| Take card payments | Card as a checkout method | Card payments |
| Prompt a customer's phone from your own UI | M-Pesa STK push, Airtel Money, Pesalink | Direct payments & payouts |
| Pay people out | M-Pesa B2C, Airtel, Pochi, Till, Paybill, bank | Direct payments & payouts |
| Hold balances for your customers | Customers and wallets | Customers & wallets |
| Move your collected float to your own account | Settlements | Settlements |
| Know the moment a payment resolves | Webhooks | Webhooks |
Pick an integration path
Almost every integration is one of two shapes.
| Direct API call | Payment link | |
|---|---|---|
| Best when | You already have a payment UI | You want a ready-made, hosted one |
| You call | POST /v1/transactions/.../initiate | POST /v1/checkout/invoices |
| The customer sees | Whatever you build | The Taifa Pay checkout, as a redirect or embedded iframe |
| Methods | M-Pesa, Airtel Money, Pesalink | M-Pesa, Airtel Money, card, bank, wallet |
| SDKs | None. Call the HTTP API. | @taifapay/payments-node (server) and @taifapay/payments-js (browser) |
Both paths end the same way. You get a pending transaction straight away, and the final outcome arrives later by webhook or from GET /v1/transactions/{id}. Never treat the initiate or invoice response as the final result.
Environments
| Environment | Base URL |
|---|---|
| Sandbox | https://sandbox.merchants.taifapay.africa/v1 |
| Production | https://merchants.taifapay.africa/v1 |
Sandbox and production behave identically. Only the host and your credentials change when you go live. Build against sandbox first.
Where to start
- Quickstart: get credentials, fetch a token and make your first payment.
- Authentication: how tokens work and how to cache them.
- Pick a path above and follow its guide.
- Webhooks: set up your endpoint and verify signatures.
- Going live: the checklist before you take real money.
Every endpoint is also listed in the API Reference, generated from the live OpenAPI spec.
Conventions used in these guides
- Examples use the sandbox host and a
$ACCESS_TOKENshell variable. externalIdis always your id for the operation. It is echoed back on transactions and webhooks so you can match them to your records.- Responses wrap the object under a named key, for example
{ "message": "...", "transaction": { ... } }.