Customers & wallets
Beyond one-off payments, the API lets you manage customers under your company and hold a running wallet balance for each of them — useful for stored value, loyalty balances, or any flow where a customer tops up once and spends later (including paying for a checkout invoice straight from their wallet).
All endpoints on this page require your company Bearer token (see Authentication) and are scoped to your company — you can only see and manage your own customers and their wallets.
There's no separate "create wallet" call. POST /v1/customers creates the customer and their wallet in one step. Every customer has a KES wallet with balance 0 from the moment they exist.
Create a customer
curl -X POST https://sandbox.merchants.taifapay.africa/v1/customers \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "+254712345678",
"externalIdentifier": "crm-cust-00123",
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"metadata": { "crmId": "abc-123" }
}'
Every field is optional (phoneNumber, externalIdentifier, email, firstName, middleName, lastName, idNumber, metadata). You'll usually want at least one way to find the customer again, though:
| Field | Notes |
|---|---|
phoneNumber | Normalised to +254XXXXXXXXX. Needed for phone lookups and M-Pesa top-ups; without it you must pass a number on each top-up. |
externalIdentifier | Your own reference for the customer (CRM id, user id, ...). Must be unique when provided. |
Creating a customer whose phoneNumber, externalIdentifier, email or idNumber is already taken fails with 409 Conflict, and the message names the field that clashed.
{
"message": "Customer created successfully",
"user": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"phoneNumber": "+254712345678",
"externalIdentifier": "crm-cust-00123",
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"status": "active",
"createdAt": "2026-07-20T09:00:00.000Z",
"wallets": [
{ "id": "a1b2c3d4e5f6a7b8", "balance": 0, "currency": "KES" }
]
}
}
Store the returned id — it's what you use to look up the customer or their wallet later. If you set an externalIdentifier, you can use that instead wherever a customer id goes.
Look up a customer
# By your platform's customer id
curl https://sandbox.merchants.taifapay.africa/v1/customers/{id} \
-H "Authorization: Bearer $ACCESS_TOKEN"
# By phone number
curl https://sandbox.merchants.taifapay.africa/v1/customers/phone/254712345678 \
-H "Authorization: Bearer $ACCESS_TOKEN"
# By your own externalIdentifier
curl https://sandbox.merchants.taifapay.africa/v1/customers/external/crm-cust-00123 \
-H "Authorization: Bearer $ACCESS_TOKEN"
All three return the customer with its current wallets[] balances. You get 404 if the customer isn't yours or no customer matches. URL-encode an externalIdentifier that contains characters such as /.
:::tip Use your own id anywhere a customer id goes
Every route that takes a customer id in the path — /v1/customers/{id} (get, update, deactivate) and all of the /v1/wallets/{customerId}/... routes below — also accepts the customer's externalIdentifier in its place, so you never have to look up our id first:
curl https://sandbox.merchants.taifapay.africa/v1/wallets/crm-cust-00123 \
-H "Authorization: Bearer $ACCESS_TOKEN"
If a value is both one customer's id and another's externalIdentifier, it is taken as the id.
:::
List customers
curl "https://sandbox.merchants.taifapay.africa/v1/customers?page=1&limit=10&orderBy=createdAt_desc" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Paginated (page, limit); optionally filter with where (a JSON string, e.g. {"status":"active"}) and sort with orderBy (field_asc / field_desc).
Update or deactivate a customer
PATCH /v1/customers/{id} # update any subset of fields (name, KYC details, status, metadata, ...)
PATCH /v1/customers/{id}/deactivate # deactivate
Deactivating a customer sweeps any remaining wallet balance to your collections account (the cash is already sitting in your float from the original top-up) and reports how much in sweptAmount.
Wallet balances (company view)
# Every wallet under your company, paginated
curl "https://sandbox.merchants.taifapay.africa/v1/wallets?page=1&limit=10" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# One customer's wallet balance
curl https://sandbox.merchants.taifapay.africa/v1/wallets/{customerId} \
-H "Authorization: Bearer $ACCESS_TOKEN"
# One customer's wallet ledger (paginated with limit/offset)
curl "https://sandbox.merchants.taifapay.africa/v1/wallets/{customerId}/entries?limit=20&offset=0" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"id": "a1b2c3d4e5f6a7b8",
"balance": 1500.5,
"currency": "KES"
}
Top up a wallet via M-Pesa or Airtel Money
To have the customer fund their wallet with M-Pesa, send them an STK prompt from your backend:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/wallets/{customerId}/topup \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 500,
"phoneNumber": "254712345678",
"description": "Top-up for order #1042"
}'
| Field | Required | Notes |
|---|---|---|
amount | yes | 1 – 10,000,000, up to 2 decimal places. |
phoneNumber | no | Number to send the prompt to. Defaults to the customer's phone number on file. |
description | no | Reason recorded on the transaction (max 140 chars). |
provider | no | mpesa (default) or airtel, to send an Airtel Money prompt instead. |
The call returns straight away with a pending transaction. Nothing is credited yet; that happens only when the customer enters their M-Pesa PIN.
{
"transactionId": "wallet-topup-a1b2c3d4e5f6a7b8",
"walletId": "a1b2c3d4e5f6a7b8",
"status": "pending",
"amount": 500,
"message": "An M-Pesa prompt has been sent to the customer. The wallet is credited once they enter their PIN."
}
Check the outcome with GET /v1/transactions/{transactionId}, or wait for the transaction.completed webhook. Once it completes, the wallet balance reflects the top-up.
| Status | When |
|---|---|
400 | No phoneNumber was sent and the customer has none on file. |
404 | The customer (or their wallet) isn't under your company. |
422 | The customer has been deactivated. |
Use this endpoint when the customer is paying in real money through M-Pesa. Use a credit adjustment when you've already received the funds some other way, or you're granting value yourself (e.g. a loyalty bonus).
Credit or debit a wallet
You can adjust a customer's wallet balance directly from your backend — credit to top it up, or debit to deduct a payment:
curl -X POST https://sandbox.merchants.taifapay.africa/v1/wallets/{customerId}/adjust \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"direction": "credit",
"amount": 500,
"description": "Loyalty bonus",
"reference": "ADJ-2024-001"
}'
| Field | Required | Notes |
|---|---|---|
direction | yes | credit (top up) or debit (deduct). |
amount | yes | 1 – 10,000,000, up to 2 decimal places. |
description | no | Reason recorded on the ledger entries (max 140 chars). |
reference | no | Your external reference for reconciliation (max 64 chars). |
The response includes the wallet balance after the adjustment:
{
"transactionId": "wallet-adjustment-credit-2b8f...",
"walletId": "a1b2c3d4e5f6a7b8",
"direction": "credit",
"amount": 500,
"balance": 2000.5,
"currency": "KES",
"message": "Wallet credited successfully"
}
A debit fails with 422 if the wallet balance is insufficient — no entry is posted. Check the balance first if you need to handle this gracefully.
This call is authorised solely by your company token and scoped to your own customers; the customer does not need to be present.
Where to go next
- Hosted checkout — a customer can pay an invoice straight from their wallet via the hosted page
- Direct payments & payouts — the M-Pesa/Pesalink endpoints wallet top-ups ride on
- Settlements — moving your own collected float to an account you control
- Webhooks — get notified when a wallet payment completes