Skip to main content

Card payments

Cards are collected through the hosted checkout, and only there. You create an invoice with card among its methods, send the customer to the checkoutUrl, and the hosted page takes the card details and charges them.

There is deliberately no direct card endpoint on this API. Card numbers, CVCs and the acquirer conversation all stay on Taifa Pay's hosted origin, so a PAN never reaches your servers or your logs and your PCI scope stays where it is.

Card is a method, not a separate integration

If you already collect with payment links, you already have the card integration — adding card to methods is the whole change. This page covers what is card-specific: what the customer sees, how a decline behaves, and how card money differs from M-Pesa money.

What is supported​

SchemesVisa and Mastercard. Any other PAN is rejected with 422 before the acquirer is called.
CurrencyThe invoice's currency (KES by default).
AmountFixed by the invoice — the page cannot change it, and neither can the customer.
CaptureImmediate. There is no separate authorise-then-capture step.
3-D SecureNot part of the current flow — the card is charged directly.
Refunds / voidsNot exposed on this API today. Raise them with Taifa Pay support.
Saved cardsNot available to merchants — nothing is tokenised for reuse.

1. Have card enabled​

Card runs on a card gateway (MPGS) that Taifa Pay configures for your company — there is nothing for you to install or key in. Ask your account manager to enable it, and to hand you sandbox card credentials for testing.

An unconfigured gateway drops card silently

The invoice only ever offers methods whose gateway is configured and active. If you ask for ["card"] and card is not enabled for your company, the invoice is still created — with card missing from its methods, and the page will not show a card tab. Check the methods array on the response rather than assuming.

2. Create the invoice​

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",
"customerName": "Jane Doe",
"customerEmail": "jane@example.com",
"methods": ["card", "mpesa_stk"],
"returnUrl": "https://merchant.example.com/thanks",
"expiresInMinutes": 30
}'
{
"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": ["card", "mpesa_stk"],
"expiresAt": "2026-08-25T12:30:00.000Z"
}
}

Offering card alongside M-Pesa is the usual choice — the customer picks a tab. Pass ["card"] alone only if you genuinely want to refuse M-Pesa. See Hosted checkout for the full field list.

Keep transactionId: it is stable for the life of the invoice and settles whichever method the customer eventually uses.

3. Send the customer to the page​

Redirect to checkoutUrl, send it by SMS or email, or embed the page with @taifapay/payments-js using the public invoiceNo (never the full URL, never your secret). Both routes are covered in Hosted checkout.

The card tab asks for number, expiry, CVC and name, and submits synchronously — see Inside the checkout page for the actual screens, including what a decline looks like.

4. Confirm the payment​

A card payment resolves while the customer is still on the page: the charge either succeeds or is declined there and then. On success the invoice moves to complete and the transaction to AWAITING_SETTLEMENT, meaning the card was charged but the money has not cleared to your float yet. It becomes COMPLETED when the acquirer settles it.

# The invoice — status plus which method was used
curl https://sandbox.merchants.taifapay.africa/v1/checkout/invoices/ABCINV-1001 \
-H "Authorization: Bearer $ACCESS_TOKEN"

# The transaction — the same id you got at creation
curl https://sandbox.merchants.taifapay.africa/v1/transactions/{transactionId} \
-H "Authorization: Bearer $ACCESS_TOKEN"

A paid card transaction carries the acquirer's receipt in receiptNumber. That receipt is what a cardholder's bank will recognise in a dispute, so store it against your order.

You are also sent webhooks, in this order:

MomenteventTypedata.status
Card approvedtransaction.completedAWAITING_SETTLEMENT
Acquirer settlestransaction.settled (subscribe as deposit.transaction.settled)COMPLETED
Acquirer settlestransaction.completedCOMPLETED

The last row is kept for older integrations; new ones should act on transaction.settled. Fulfil the order on the first row and treat the second as confirmation that the cash is yours to spend.

De-duplicate on id, event type and status

A card payment sends transaction.completed twice. If you de-duplicate on data.id plus eventType alone, the second one looks like a repeat. Include data.status and make each step idempotent. Poll the invoice or transaction as a backstop, for example when the customer lands on your returnUrl and again on a reconciliation sweep.

Declines and errors​

A decline is not an error in your integration — it is an ordinary outcome, and the customer can fix it themselves.

What happenedThe page shows
The acquirer declined the cardCard declined: <acquirer message>, inline above the Pay button
A card that is neither Visa nor MastercardOnly Visa and Mastercard are supported.
The link has expired, or the invoice is already paidThe corresponding session message; no charge is attempted

A decline leaves the invoice open and payable. The session does not reset, the customer can correct a digit or try another card, and each attempt goes to the acquirer under a fresh order id — so a retry after a decline is never mistaken for a duplicate charge.

Because retries are normal, do not mark an order failed on the first decline. Wait for the invoice to expire, or for the customer to abandon it.

When the money is yours​

Card money does not behave like M-Pesa money.

  • An M-Pesa collection lands in your float immediately and can go straight back out on a payout or a settlement.
  • A card collection is captured at the processor first and reaches your float when the acquirer settles it. The payment is complete and irreversible from the customer's point of view long before the cash clears to the bank.

Ask your account manager for your settlement timetable if you are planning cash flow around card volume.

awaiting_settlement is not pending_settlement

Card money waiting to clear is awaiting_settlement — money coming in that you cannot spend yet. pending_settlement is the opposite: money you can already spend, sitting behind a settlement request you raised. Never let a status filter or a badge treat them as the same thing.

What never touches your server​

  • Card details are entered on the hosted origin and passed straight to the acquirer. They are never persisted, never logged, and never returned to you.
  • Your backend only ever handles the invoiceNo, the transactionId and the resulting receipt.
  • returnUrl is navigation, not proof. The customer arriving there means their browser was redirected, nothing more — always confirm the outcome with the API before releasing goods.

Testing​

Use the sandbox host with the sandbox card credentials Taifa Pay issues alongside your gateway. Worth exercising before you go live:

  • a successful charge, checking transactionCode reaches your order record;
  • a declined card, checking your UI does not cancel the order;
  • an expired link, so you know what a late customer sees.

Where to go next​