Skip to main content

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.

Creating a customer creates their wallet

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:

FieldNotes
phoneNumberNormalised to +254XXXXXXXXX. Needed for phone lookups and M-Pesa top-ups; without it you must pass a number on each top-up.
externalIdentifierYour 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"
}'
FieldRequiredNotes
amountyes1 – 10,000,000, up to 2 decimal places.
phoneNumbernoNumber to send the prompt to. Defaults to the customer's phone number on file.
descriptionnoReason recorded on the transaction (max 140 chars).
providernompesa (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.

StatusWhen
400No phoneNumber was sent and the customer has none on file.
404The customer (or their wallet) isn't under your company.
422The customer has been deactivated.
Top-up vs. credit

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"
}'
FieldRequiredNotes
directionyescredit (top up) or debit (deduct).
amountyes1 – 10,000,000, up to 2 decimal places.
descriptionnoReason recorded on the ledger entries (max 140 chars).
referencenoYour 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"
}
Debits can't overdraw

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