iSmartPay API
Collect money from payers and send money to recipients from your iSmartPay wallet.
Authentication
Every operation takes a bearer token from an API credential (a client id and a client secret you create in the developer console). Get a token by calling POST /v1/oauth/token on the iSmartPay identity service with your client id and secret, then send it as Authorization: Bearer <token>. Tokens are short-lived, so request a new one when you get a 401. A signed-in user’s token is not accepted here.
Each operation needs a permission on the credential, named in its description. A credential works in one environment, test or live, and only against that environment’s API; the other returns 403 environment_mismatch.
Amounts
Amounts are decimal strings in major units, for example "120.00", never numbers.
Retrying safely
Every POST needs an Idempotency-Key header. If a request times out or fails with a 5xx, send it again with the same key and body. It is applied once. Each request also gets a Request-Id response header; quote it when you contact support.
Rate limits
Requests are limited per credential. Past the limit you get 429 rate_limited and a Retry-After header.
Errors
Errors look like {"error":{"code":"...","message":"..."}}. Branch on code.
https://{host}Collections
Collect money from a payer into your wallet.
- POSTCollect money from a payer
/v1/collections - GETGet a collection
/v1/collections/{reference} - GETPreview the fee on a collection
/v1/fee-quotes/collections
Checkouts
Hosted payment links your customers open to pay you.
- GETList hosted checkouts
/v1/checkouts - POSTCreate a hosted checkout
/v1/checkouts - GETGet a hosted checkout
/v1/checkouts/{checkoutId} - POSTCancel a hosted checkout
/v1/checkouts/{checkoutId}/cancel
Payouts
Send money from your wallet to a recipient.
- POSTSend money to a recipient
/v1/payouts - POSTSend up to 100 payouts at once
/v1/payout-batches - GETGet a payout
/v1/payouts/{reference} - GETPreview the fee on a payout
/v1/fee-quotes/payouts
Utilities
Buy airtime and data for a mobile number.
- GETList airtime and data products
/v1/utility-products - GETPreview the fee on a utility purchase
/v1/fee-quotes/utilities - POSTBuy airtime or data
/v1/utility-purchases - GETGet a utility purchase
/v1/utility-purchases/{reference}
Settlements
Paying your wallet out to your own verified bank and mobile money accounts.
- GETGet where and when settlements are paid
/v1/settlement-policy - PUTSet where and when settlements are paid
/v1/settlement-policy - DELETETurn settlement off
/v1/settlement-policy - GETList settlement runs
/v1/settlements - POSTSettle now
/v1/settlements - GETGet the latest settlement run
/v1/settlements/latest - GETGet a settlement run
/v1/settlements/{id} - POSTRetry a failed settlement run
/v1/settlements/{id}/resettlements
Transfers
Sending money from your wallet to another iSmartPay business, by handle.
- GETCheck who a handle belongs to
/v1/recipients/{handle} - POSTSend money to another business
/v1/transfers - GETGet a transfer
/v1/transfers/{reference}
Reference
Providers and account holders.
- GETList the providers you can use
/v1/payment-methods - GETLook up the name on a mobile money number
/v1/party-lookups
Account
Your wallet balances and limits.
- GETRead your limits and what is left
/v1/limits - GETRead your wallet balances
/v1/wallet - GETList your transactions
/v1/transactions
Webhooks
Events sent to the endpoints you register in the console.
- POSTcollection.accepted
collection.accepted - POSTcollection.status_changed
collection.status_changed - POSTpayout.accepted
payout.accepted - POSTpayout.status_changed
payout.status_changed - POSTutility_purchase.accepted
utility_purchase.accepted - POSTutility_purchase.status_changed
utility_purchase.status_changed - POSTsettlement.status_changed
settlement.status_changed - POSTtransfer.status_changed
transfer.status_changed - POSTtransfer.received
transfer.received
Events
The same events, listed on request, for catching up after missed webhooks.