Skip to main content

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 toUseGuide
Get paid without building a payment pageHosted checkout and payment linksHosted checkout
Take card paymentsCard as a checkout methodCard payments
Prompt a customer's phone from your own UIM-Pesa STK push, Airtel Money, PesalinkDirect payments & payouts
Pay people outM-Pesa B2C, Airtel, Pochi, Till, Paybill, bankDirect payments & payouts
Hold balances for your customersCustomers and walletsCustomers & wallets
Move your collected float to your own accountSettlementsSettlements
Know the moment a payment resolvesWebhooksWebhooks

Pick an integration path​

Almost every integration is one of two shapes.

Direct API callPayment link
Best whenYou already have a payment UIYou want a ready-made, hosted one
You callPOST /v1/transactions/.../initiatePOST /v1/checkout/invoices
The customer seesWhatever you buildThe Taifa Pay checkout, as a redirect or embedded iframe
MethodsM-Pesa, Airtel Money, PesalinkM-Pesa, Airtel Money, card, bank, wallet
SDKsNone. 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​

EnvironmentBase URL
Sandboxhttps://sandbox.merchants.taifapay.africa/v1
Productionhttps://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​

  1. Quickstart: get credentials, fetch a token and make your first payment.
  2. Authentication: how tokens work and how to cache them.
  3. Pick a path above and follow its guide.
  4. Webhooks: set up your endpoint and verify signatures.
  5. 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_TOKEN shell variable.
  • externalId is 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": { ... } }.