Wallet API — check balance & top up (mobile money)

Delivery orders billed to your partner account (e.g. mobile_money_unpaid) draw down a delivery wallet balance against a credit limit. The endpoints below let you check the balance and top it up programmatically — full schemas are in the API Reference.

All wallet endpoints require the delivery:wallet:topup scope and a production API key.

Get wallet balance

GET /api/v1/delivery/wallet.balance

Returns the partner's delivery wallet balance in GHS.

Initiate a top-up

POST /api/v1/delivery/wallet.topup.initiate

Starts a wallet top-up: persists a token → partner mapping and returns a payment gateway checkout URL.

{
  "amount_ghs": 500
}

Send the partner to the returned checkout URL to complete payment.

Verify a top-up

POST /api/v1/delivery/wallet.topup.verify

Verifies a top-up's payment status with the gateway and, on success, credits the wallet exactly once — this endpoint is idempotent, so it's safe to call again if you're unsure whether the first call succeeded.

{
  "client_reference": "topup_abc123..."
}

Use the client_reference returned from the initiate call (or your own reference, if you generated the checkout session yourself).

Credit limit behavior

Partners with a credit limit can accumulate unpaid delivered orders up to that limit before new orders are blocked. Once the outstanding balance reaches the credit limit, order creation on the delivery service is rejected until the wallet is topped up or invoices are settled.

How it fits together

1. Check wallet.balance before placing high-value orders on credit.
2. When the balance runs low, call wallet.topup.initiate and redirect the partner (or their finance user) to the checkout URL.
3. On return, call wallet.topup.verify with the same reference to confirm the credit landed.