Skip to content

Build payments into your product.

One REST API for Mobile Money collections, payouts, airtime and settlements. Build against the sandbox, then go live with the same code.

  1. Get a token.
  2. Create a collection.
  3. Get a webhook.

cURL

curl -X POST "$API/v1/collections" \  -H "Authorization: Bearer $TOKEN" \  -H "Idempotency-Key: order-1042" \  -H "Content-Type: application/json" \  -d '{    "reference": "order-1042",    "amount": "120.00",    "currency": "GHS",    "provider": "telecel",    "payer": { "type": "msisdn", "value": "233000000001" }  }'

Node.js

const res = await fetch(`${API}/v1/collections`, {  method: "POST",  headers: {    Authorization: `Bearer ${token}`,    "Idempotency-Key": "order-1042",    "Content-Type": "application/json",  },  body: JSON.stringify({    reference: "order-1042",    amount: "120.00",    currency: "GHS",    provider: "telecel",    payer: { type: "msisdn", value: "233000000001" },  }),});

Python

import requestsres = requests.post(    f"{API}/v1/collections",    headers={        "Authorization": f"Bearer {token}",        "Idempotency-Key": "order-1042",    },    json={        "reference": "order-1042",        "amount": "120.00",        "currency": "GHS",        "provider": "telecel",        "payer": {"type": "msisdn", "value": "233000000001"},    },)

Response

HTTP/1.1 202 Accepted{  "reference": "order-1042",  "status": "accepted",  "amount": "120.00",  "currency": "GHS",  "provider": "telecel"}

How a payment flows.

From your server to the payer's phone and back, in a few calls you can read.

  1. Get a token

    Swap your client ID and secret for an access token. It lasts five minutes.

    POST /v1/oauth/token
  2. Create a collection

    Send the amount, the network and the payer's number. You get 202 straight back.

    POST /v1/collections
  3. The payer approves

    The status moves from accepted to dispatched, then ends as settled, failed or expired.

    accepted → dispatched → settled
  4. Your webhook fires

    iSmartPay sends a signed POST to your server when the status changes.

    collection.status_changed

GET/v1/collections/order-1042

  1. "status":"accepted"
  2. "status":"dispatched"
  3. "status":"settled"or failed, expired

POSTyour webhookcollection.status_changed

More than collections.

Send customers to a pay page you never have to build, charge them on a schedule, or hold money until an order is done.

  • Hosted checkout.

    Create a checkout and send your customer to its link. They pay with MTN MoMo, Telecel Cash or their iSmartPay wallet, on a page with your name and colour.

    POST /v1/checkouts
    Checkout preview in the iSmartPay developer portal: a pay page for Demo Store Ghana asking for GHS 120 with MTN MoMo, Telecel Cash and iSmartPay
  • Subscriptions.

    Charge a customer the same amount every day, week or month after they agree once. Pause, resume or cancel from the API or the portal. Ask us to switch subscriptions on for your business.

    POST /v1/subscriptions
    The subscriptions page in the iSmartPay developer portal, listing weekly and monthly subscriptions with their price, next charge and status
  • Escrow holds.

    Set money aside for someone, then pay it to them or give it back. Built for marketplaces that pay sellers once the goods arrive.

    POST /v1/holds
    1. heldThe money is set aside for a seller, a branch wallet or a mobile money number.
    2. paid_outThe goods arrived. Pay it to them.
    3. returnedThe order fell through. Give it back.

Everything else in the API.

The pieces you reach for once payments are flowing.

  • Sub-accounts

    Open another wallet of your business for each client or product. It sits under your one verification and your limits.

    POST /v1/sub-accounts
  • Wallet moves

    Shift money from one of your wallets to another in a single step.

    POST /v1/wallet-moves
  • Pay by handle

    Find another iSmartPay business by its @handle and send money straight to its wallet.

    POST /v1/transfers
  • Payment requests

    Ask another iSmartPay account to pay you. They approve in the app or the Business console with their PIN, and nothing moves until they do.

    payment_request.received
  • Payout batches

    Pay many people in one call. Each item is accepted or refused on its own, so one refusal doesn't stop the rest.

    POST /v1/payout-batches
  • Reversals

    Undo a finished payment. The original is never edited: a second movement sends the money back and is linked to it.

    POST /v1/payouts/{reference}/reversal-requests
  • Daily statements

    Ask for any day and get each wallet's opening and closing balance, every transaction, and every escrow hold.

    GET /v1/statements?date=
  • Settlements

    Set a settlement policy, see every settlement run to your bank, and follow each one by webhook.

    PUT /v1/settlement-policy

The endpoints you will use.

Collections

  • POST/v1/collectionsAsk a payer to approve a payment
  • GET/v1/collections/{reference}Check where a collection is
  • POST/v1/fee-quotes/collectionsQuote the fee before you charge

Payouts

  • POST/v1/payoutsSend money to a mobile money number
  • POST/v1/payout-batchesPay many people in one request
  • GET/v1/payouts/{reference}Check a payout

Hosted checkout

  • POST/v1/checkoutsCreate a pay page and send your customer to it
  • GET/v1/checkouts/{checkoutId}Check whether it was paid
  • PUT/v1/checkout/appearanceSet your name, colour and payment methods

Subscriptions

  • POST/v1/subscriptionsCharge a customer on a schedule after they agree once
  • POST/v1/subscriptions/{id}/pausePause, resume or cancel
  • GET/v1/subscriptions/{id}/chargesEvery charge and its result

Escrow holds

  • POST/v1/holdsSet money aside for someone
  • POST/v1/holds/{reference}/pay-outPay it to them
  • POST/v1/holds/{reference}/returnGive it back

Wallets and sub-accounts

  • POST/v1/sub-accountsOpen another wallet for a client or product
  • POST/v1/wallet-movesMove money between your own wallets
  • GET/v1/statementsOne day of every wallet, ready to reconcile

Transfers and reversals

  • GET/v1/recipients/{handle}Look up a business by its handle
  • POST/v1/transfersPay another iSmartPay business
  • POST/v1/payouts/{reference}/reversal-requestsAsk to undo a finished payout

Airtime and data

  • GET/v1/utility-productsList what you can sell
  • POST/v1/utility-purchasesBuy airtime or data for a number

Money and records

  • GET/v1/walletYour balance
  • GET/v1/settlementsSettlement runs to your bank
  • GET/v1/transactionsEvery movement on your account
  • GET/v1/eventsEvents, if you would rather poll

Webhooks you can trust.

When a payment changes, iSmartPay sends a signed POST to your HTTPS endpoint, so you never have to poll. Each delivery carries a Webhook-Id, a timestamp and an HMAC-SHA256 signature to check before you act.

  • collection.accepted
  • collection.status_changed
  • payout.accepted
  • payout.status_changed
  • checkout.paid
  • subscription.charge_succeeded
  • hold.status_changed
  • utility_purchase.status_changed
  • settlement.status_changed
  • transfer.received
  • transfer.status_changed
  • payment_request.received
verify-webhook.js
import { createHmac, timingSafeEqual } from "node:crypto";const signed = `${id}.${timestamp}.${rawBody}`;const expected = createHmac("sha256", secret)  .update(signed)  .digest("base64");const given = header.replace("v1,", "");const ok = timingSafeEqual(Buffer.from(given), Buffer.from(expected));

Set up in the portal.

A setup guide walks you from API access to your first webhook. Each endpoint shows its events and every delivery, with retries, so you can send a test event and watch it land.

The iSmartPay developer portal webhooks page with a five-step setup guide and a registered endpoint with its subscribed events

Built to be predictable.

  • Safe to retry

    Send an Idempotency-Key with every write. Retry the same request and you get the same result, never a double charge.

    Idempotency-Key: order-1042
  • Errors you can act on

    • 401Get a new token
    • 409You reused a key with a different body
    • 429Comes with Retry-After

See every call you make.

The developer portal shows your traffic, error rate and latency, every request with its status, and your test and live keys.

Open the developer portal
The iSmartPay developer portal API requests page, with request counts, error rate and a chart of requests per hour
The iSmartPay developer portal API keys page, listing live and test keys with masked client IDs

From sandbox to live.

Build against the sandbox, then go live with the same code.

  1. test

    Create a test key

    Create a business account on the developer portal, open API keys and create a test key. The client secret is shown once, so store it safely.

  2. sandbox

    Build against the sandbox

    Test keys, test numbers and the same endpoints. Nothing you do in test moves real money.

  3. live

    Go live once you are verified

    Verify your business in the live portal: confirm your phone, add your owners and your TIN, and answer a few risk questions. Then create live keys and point your code at the live base URL. Test and live keys, endpoints and webhook secrets are kept separate.

Questions developers ask.

How do I get API access?

Create a business account on the developer portal, open API keys and create a test key. The client secret is shown once, so store it safely.

How long does an access token last?

Five minutes. Request a new one with your client credentials when it expires.

How do I test without real money?

Use a test key against the sandbox, with the test numbers listed in the sandbox guide. Test and live keys, endpoints and webhook secrets are kept separate.

How do I know a payment finished?

Register a webhook and listen for collection.status_changed, or fetch the collection by its reference. A collection ends as settled, failed or expired.

When can I go live?

Once your business is verified. You then create live keys in the live portal and point your code at the live base URL.

Start with a test key.

Create a business account on the developer portal, open API keys and create a test key.