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)

json
{  "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"}

Request parameters

ParameterTypeRequiredDescription
emailstringYesCustomer email
first_namestringYesFirst name
last_namestringYesLast name
amountstringYesAmount as decimal string
currencystringYesCurrency code
referencestringYesYour unique reference
redirectUrlstringNoPost-payment redirect
descriptionstringNoDescription shown where supported
checkout_display_namestringNoName shown on checkout
customer_phone_numberstringNoE.164 phone when known

Success response (shape)

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

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

Integration flow

  1. Call initialize with the correct currency and amount.
  2. Open or redirect to the returned checkout URL.
  3. Customer selects mobile money, enters details, 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>

Do not hardcode network or bank codes; load options from the API.

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.