How TeePay works
The payment lifecycle, who confirms a payment and when it is safe to deliver.
Every TeePay payment moves through the same lifecycle, whatever the channel.
Your server creates the payment
You call TeePay with a secret key and an Idempotency-Key. TeePay checks your account, scopes,
limits and pricing, then records the payment before contacting any provider.
The customer approves it
Depending on the product, the customer approves a USSD prompt on their phone, pays on TeePay's hosted checkout or pays a Control Number through their bank or mobile wallet.
TeePay verifies and posts it
TeePay confirms the outcome with the provider, calculates fees and posts the payment to your ledger. Only a ledger-posted payment counts as money received.
You are notified
TeePay sends a signed webhook and the status becomes final. Your server can also read the status at any time.
Payment statuses
| Status | Meaning | Final |
|---|---|---|
created | Recorded by TeePay, not yet sent to a provider. | No |
pending | Sent; waiting for the customer or provider. | No |
processing | The provider is completing the payment. | No |
succeeded | Verified and posted to your ledger. Safe to fulfil. | Yes |
failed | Not completed. status_detail is cancelled or expired when known. | Yes |
reversed | A completed payment was reversed by the provider. | Yes |
refunded | The payment was refunded. | Yes |
Never fulfil on a redirect
A customer returning to your website, a provider prompt or an HTTP 202 response does not mean a
payment succeeded. Fulfil only on succeeded (or a checkout session's paid) from a webhook or an
API read made by your server.
Fees and settlement
Collection fees are deducted from the amount received; your ledger is credited with the net amount. Fees are set for your account and shown in the dashboard. Payouts are charged a merchant fee that is shown in every payout quote before you confirm it.
NextAuthenticationAPI keys, scopes and how to keep them safe.