Skip to main content

Quickstart

By the end of this page you will have credentials, an access token, a pending payment and a way to check its outcome. Everything runs against sandbox.

1. Get set up in the portal​

Our team creates your merchant account. Once it exists, two things are self-serve from the portal:

  1. Create client credentials. Go to Integrations → Credentials and generate a client_id and client_secret. The secret is shown once, so store it in a secret manager. Sandbox and production use separate pairs.
  2. Register a webhook. Go to Integrations → Webhooks, add the HTTPS URL we should POST to, and copy the signing secret. You can skip this for your first call and add it before you build further. See Webhooks.
Sandbox in the portal

Use the sandbox toggle in the portal to switch to sandbox. Sandbox has its own credentials and its own webhook settings, so generate them there.

Keep the secret on your server. Never put it in a mobile app or browser code.

2. Get an access token​

Exchange the credentials for a short-lived Bearer token. The Node SDK does this for you, so skip ahead if you use it. The full lifecycle is in Authentication.

curl -X POST https://sandbox.merchants.taifapay.africa/v1/auth/token \
-u "your_client_id:your_client_secret" \
-H "Content-Type: application/json" \
-d '{"grant_type": "client_credentials"}'
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
"expires_in": "3599",
"token_type": "Bearer"
}

3. Make your first payment​

Choose the path that matches how you plan to integrate. Not sure? See Pick an integration path.

Create an invoice on your server. The amount is fixed here, so this step always needs your secret.

curl -X POST https://sandbox.merchants.taifapay.africa/v1/checkout/invoices \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 1500,
"accountReference": "INV-1001",
"description": "Order #1001 - 2x widget",
"customerPhone": "254712345678"
}'

The response gives you everything you need:

{
"message": "Invoice created",
"invoice": {
"transactionId": "a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e",
"checkoutUrl": "https://pay.taifapay.africa/pay/ABCINV-1001",
"invoiceNo": "ABCINV-1001",
"amount": 1500,
"currency": "KES",
"status": "open",
"methods": ["mpesa_stk", "card"],
"expiresAt": "2026-07-17T12:30:00.000Z"
}
}

Open checkoutUrl in a browser to pay. To keep the customer on your own page instead, embed it with the browser SDK. Both options are in Hosted checkout.

4. Check the outcome​

Every money movement is a transaction with a stable id. It moves from PENDING to COMPLETED or FAILED. Fetch it any time:

curl https://sandbox.merchants.taifapay.africa/v1/transactions/a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e \
-H "Authorization: Bearer $ACCESS_TOKEN"

Polling works for a first test, but production integrations should treat webhooks as the source of truth and keep polling only as a reconciliation fallback. Check your endpoint with POST /v1/webhooks/test.

Next steps​