Mobile money collection

Collect from customers via mobile money in supported markets. Customers approve on their handset; you integrate using the same hosted checkout pattern as card collection.

For payment instructions returned directly in API responses (no hosted UI), use a deposit quote flow via Quotes and Resource quotes.

Initialize payment

Same initialization as card collection: POST /api/v1/client/checkout/initialize. Set currency to the mobile-money corridor you intend (for example GHS, KES, UGX, TZS when available).

Authentication

Use Authentication for signing.

Request body (example)

{  "email": "customer@example.com",  "first_name": "Kwame",  "last_name": "Asante",  "amount": "50.00",  "currency": "GHS",  "reference": "ORDER-67890",  "redirectUrl": "https://your-website.com/payment-success",  "description": "Payment for order #67890",  "checkout_display_name": "Your Business",  "customer_phone_number": "+233241234567",  "operator": "MTN",  "hide_card": true}

Request parameters

Success response (shape)

{  "success": true,  "message": "Transaction Initialized Successfully",  "data": {    "access_code": "…",    "checkout_link": "https://…",    "transactionRef": "…",    "reference": "ORDER-67890",    "redirectUrl": "https://your-website.com/payment-success"  }}

When operator is provided, the checkout page will:

• Show only mobile_money as a payment method.
• Pre-select the operator's network — the payer only needs to enter their phone number.
• Return the operator value in the GET /api/v1/checkout/:access_code response.

Available operators

The following operator codes are supported per currency:

Operator codes are case-insensitive (e.g. mtn, Mtn, and MTN are all valid).

Redirect the customer to checkout_link and store transactionRef with your reference.

Integration flow

Without operator — payer chooses the network:

1. Call initialize with the correct currency and amount.
2. Open or redirect to the returned checkout URL.
3. Customer selects mobile money, picks their network, enters phone number, and approves on device.
4. Confirm status using webhooks and optionally verify.

With operator — network is pre-selected by the merchant:

1. Call initialize with currency and the desired operator code (see Available operators).
2. Open or redirect to the returned checkout URL.
3. Network is already locked — customer only enters their phone number and approves on device.
4. Confirm status using webhooks and optionally verify.

Corridors and discovery

Supported currencies depend on environment and configuration. Query:

• GET /api/v1/client/currencies
• GET /api/v1/client/banks?currency=<CODE>

When passing an operator at initialization, the checkout page shows only mobile_money as the available method and locks the network to the resolved operator. The hosted checkout returns the resolved operator name in the operator field of the GET /api/v1/checkout/:access_code response.

API-first alternative

See Quotes for DEPOSIT-style flows: create quote, accept, use returned payment details, track via webhooks.

Verify status

GET /api/v1/client/payment/verify?reference=<transaction_reference> — verify with the Transfaar transaction reference.

GET /api/v1/client/payment/verify?origin_reference=<your_checkout_reference> — verify with the checkout reference you supplied during initialization.

Both forms return the same response shape; see Card collection — Verify.

Webhooks

Payload shape aligns with other collection types (reference, amount, currency, status fields). Verify signatures as in Webhooks.

Practices

1. Send customer_phone_number when you have it to reduce friction.
2. Expect variable approval time on device; do not rely on redirect alone.
3. Store transactionRef and your reference together.
4. Treat webhook delivery as the source of truth for final status.