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:
- Create client credentials. Go to Integrations → Credentials and generate a
client_idandclient_secret. The secret is shown once, so store it in a secret manager. Sandbox and production use separate pairs. - Register a webhook. Go to Integrations → Webhooks, add the HTTPS URL we should
POSTto, and copy the signing secret. You can skip this for your first call and add it before you build further. See Webhooks.
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
- Node.js
- Python
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"}'
const res = await fetch('https://sandbox.merchants.taifapay.africa/v1/auth/token', {
method: 'POST',
headers: {
Authorization: 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64'),
'Content-Type': 'application/json',
},
body: JSON.stringify({ grant_type: 'client_credentials' }),
});
const { access_token } = await res.json();
import base64
import requests
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
response = requests.post(
"https://sandbox.merchants.taifapay.africa/v1/auth/token",
headers={
"Authorization": f"Basic {credentials}",
"Content-Type": "application/json",
},
json={"grant_type": "client_credentials"},
)
access_token = response.json()["access_token"]
{
"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.
- Payment link
- Direct API call
Create an invoice on your server. The amount is fixed here, so this step always needs your secret.
- cURL
- Node.js (SDK)
- Python
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"
}'
// npm install @taifapay/payments-node
import { TaifaPayments } from "@taifapay/payments-node";
const taifa = new TaifaPayments({
clientId: process.env.TAIFA_CLIENT_ID!,
clientSecret: process.env.TAIFA_CLIENT_SECRET!,
environment: "sandbox", // or "production"
});
const invoice = await taifa.invoices.create({
amount: 1500,
accountReference: "INV-1001",
description: "Order #1001 - 2x widget",
customerPhone: "254712345678",
});
// invoice.checkoutUrl -> redirect the customer here
// invoice.invoiceNo -> or hand to the browser SDK to embed
// invoice.transactionId -> the id you track
The SDK exchanges and caches the access token for you and retries once on a mid-flight 401.
response = requests.post(
"https://sandbox.merchants.taifapay.africa/v1/checkout/invoices",
headers={
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json={
"amount": 1500,
"accountReference": "INV-1001",
"description": "Order #1001 - 2x widget",
"customerPhone": "254712345678",
},
)
invoice = response.json()["invoice"]
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.
Send an M-Pesa STK push straight to a phone. See Direct payments & payouts for every other method.
- cURL
- Node.js
- Python
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"
}'
const res = await fetch('https://sandbox.merchants.taifapay.africa/v1/transactions/m-pesa/c2b/initiate', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
phoneNumber: '0712345678',
amount: 100,
accountReference: 'Account123',
transactionDesc: 'Top-up',
externalId: 'your-transaction-id',
}),
});
const { transaction } = await res.json();
response = requests.post(
"https://sandbox.merchants.taifapay.africa/v1/transactions/m-pesa/c2b/initiate",
headers={
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json={
"phoneNumber": "0712345678",
"amount": 100,
"accountReference": "Account123",
"transactionDesc": "Top-up",
"externalId": "your-transaction-id",
},
)
transaction = response.json()["transaction"]
The customer enters their PIN on the prompt, and the transaction resolves shortly after.
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
- Node.js (SDK)
curl https://sandbox.merchants.taifapay.africa/v1/transactions/a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e \
-H "Authorization: Bearer $ACCESS_TOKEN"
const txn = await taifa.transactions.get(invoice.transactionId);
// or: await taifa.invoices.get(invoice.invoiceNo)
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
- Take it further: Hosted checkout, Card payments or Direct payments & payouts.
- Handle results reliably: Webhooks.
- Ready for real money: Going live.