--- seo: description: >- Collect money from payers and send money to recipients from your iSmartPay wallet. sidebar: label: Overview title: 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 `. 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`. Version 1.0.0 Base URL: `https://{host}` ## Collections Collect money from a payer into your wallet. - [`POST /v1/collections`](/reference/collections/create-collection) — Collect money from a payer. - [`GET /v1/collections/{reference}`](/reference/collections/get-collection) — Get a collection. - [`GET /v1/fee-quotes/collections`](/reference/collections/quote-collection-fee) — Preview the fee on a collection. ## Checkouts Hosted payment links your customers open to pay you. - [`GET /v1/checkouts`](/reference/checkouts/list-checkouts) — List hosted checkouts. - [`POST /v1/checkouts`](/reference/checkouts/create-checkout) — Create a hosted checkout. - [`GET /v1/checkouts/{checkoutId}`](/reference/checkouts/get-checkout) — Get a hosted checkout. - [`POST /v1/checkouts/{checkoutId}/cancel`](/reference/checkouts/cancel-checkout) — Cancel a hosted checkout. ## Payouts Send money from your wallet to a recipient. - [`POST /v1/payouts`](/reference/payouts/create-payout) — Send money to a recipient. - [`POST /v1/payout-batches`](/reference/payouts/create-payout-batch) — Send up to 100 payouts at once. - [`GET /v1/payouts/{reference}`](/reference/payouts/get-payout) — Get a payout. - [`GET /v1/fee-quotes/payouts`](/reference/payouts/quote-payout-fee) — Preview the fee on a payout. ## Utilities Buy airtime and data for a mobile number. - [`GET /v1/utility-products`](/reference/utilities/list-utility-products) — List airtime and data products. - [`GET /v1/fee-quotes/utilities`](/reference/utilities/quote-utility-fee) — Preview the fee on a utility purchase. - [`POST /v1/utility-purchases`](/reference/utilities/create-utility-purchase) — Buy airtime or data. - [`GET /v1/utility-purchases/{reference}`](/reference/utilities/get-utility-purchase) — Get a utility purchase. ## Settlements Paying your wallet out to your own verified bank and mobile money accounts. - [`GET /v1/settlement-policy`](/reference/settlements/get-settlement-policy) — Get where and when settlements are paid. - [`PUT /v1/settlement-policy`](/reference/settlements/put-settlement-policy) — Set where and when settlements are paid. - [`DELETE /v1/settlement-policy`](/reference/settlements/delete-settlement-policy) — Turn settlement off. - [`GET /v1/settlements`](/reference/settlements/list-settlements) — List settlement runs. - [`POST /v1/settlements`](/reference/settlements/settle-now) — Settle now. - [`GET /v1/settlements/latest`](/reference/settlements/get-latest-settlement) — Get the latest settlement run. - [`GET /v1/settlements/{id}`](/reference/settlements/get-settlement) — Get a settlement run. - [`POST /v1/settlements/{id}/resettlements`](/reference/settlements/retry-settlement) — Retry a failed settlement run. ## Transfers Sending money from your wallet to another iSmartPay business, by handle. - [`GET /v1/recipients/{handle}`](/reference/transfers/get-recipient) — Check who a handle belongs to. - [`POST /v1/transfers`](/reference/transfers/create-transfer) — Send money to another business. - [`GET /v1/transfers/{reference}`](/reference/transfers/get-transfer) — Get a transfer. ## Reference Providers and account holders. - [`GET /v1/payment-methods`](/reference/reference/list-payment-methods) — List the providers you can use. - [`GET /v1/party-lookups`](/reference/reference/lookup-party) — Look up the name on a mobile money number. ## Account Your wallet balances and limits. - [`GET /v1/limits`](/reference/account/get-limits) — Read your limits and what is left. - [`GET /v1/wallet`](/reference/account/get-wallet) — Read your wallet balances. - [`GET /v1/transactions`](/reference/account/list-transactions) — List your transactions. ## Webhooks Events sent to the endpoints you register in the console. - [`POST collection.accepted`](/reference/webhooks/webhook-collection-accepted) — collection.accepted. - [`POST collection.status_changed`](/reference/webhooks/webhook-collection-status-changed) — collection.status\_changed. - [`POST payout.accepted`](/reference/webhooks/webhook-payout-accepted) — payout.accepted. - [`POST payout.status_changed`](/reference/webhooks/webhook-payout-status-changed) — payout.status\_changed. - [`POST utility_purchase.accepted`](/reference/webhooks/webhook-utility-purchase-accepted) — utility\_purchase.accepted. - [`POST utility_purchase.status_changed`](/reference/webhooks/webhook-utility-purchase-status-changed) — utility\_purchase.status\_changed. - [`POST settlement.status_changed`](/reference/webhooks/webhook-settlement-status-changed) — settlement.status\_changed. - [`POST transfer.status_changed`](/reference/webhooks/webhook-transfer-status-changed) — transfer.status\_changed. - [`POST transfer.received`](/reference/webhooks/webhook-transfer-received) — transfer.received. ## Events The same events, listed on request, for catching up after missed webhooks. - [`GET /v1/events`](/reference/events/list-events) — Catch up on events you missed.