Mobile money

Last updated: 2026-05-22

Use mobile money when the selected market in GET /merchant/api/v1/catalog returns mobile_money in methodsIn or methodsOut.

For market coverage, see Coverage. For operator-code discovery, see Mobile money operators. For voucher-based pay-ins, see Vouchers.

Integration sequence

1. Call GET /merchant/api/v1/catalog with a publishable key and choose the market for the flow you are implementing.
2. For mobile-money pay-ins, call GET /merchant/api/v1/payins/mmo for the selected market and request context.
3. For mobile-money pay-outs, call GET /merchant/api/v1/payouts/mmo for the selected market and request context.
4. Build your operator selector from operators[].name and store the selected operators[].operator value.
5. Reuse the selected operator exactly as returned in the payment request.
6. For voucher-based H2H pay-ins, collect and send mobileMoneyDetails.voucherPin.
7. Track the latest accepted status through webhooks and GET /merchant/api/v1/payment/{id}.

Operator fields

Flow	Create endpoint	Operator field
H2P pay-in	POST /merchant/api/v1/payins/initialize	mobileMoneyOperator
H2H pay-in	POST /merchant/api/v1/payins/create	mobileMoneyDetails.operator
Pay-out	POST /merchant/api/v1/payouts/create	mobileMoneyDetails.operator

Operator codes are machine-readable discovery values. Treat them as opaque and case-sensitive. Do not map, lowercase, rename, or hard-code them as a fixed enum in your integration.

Voucher-based H2H pay-ins also use mobileMoneyDetails.voucherPin when the selected market/operator requires voucher collection.

H2P pay-in

curl -X POST "https://merchants-api.example.com/merchant/api/v1/payins/initialize" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currencyCode": "GHS",
    "countryCode": "GH",
    "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY",
    "merchantReference": "MM-H2P-1001",
    "redirectUrl": "https://merchant.example/return",
    "trafficVertical": "TRAFFIC_VERTICAL_OTHER",
    "customerSegment": "CUSTOMER_SEGMENT_FTD",
    "mobileMoneyOperator": "<operator_from_discovery>"
  }'

If paymentOrder.paymentUrl is returned, redirect the customer there. The redirect return is informational; reconcile status through webhook delivery or payment status polling.

H2H pay-in

curl -X POST "https://merchants-api.example.com/merchant/api/v1/payins/create" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currencyCode": "GHS",
    "countryCode": "GH",
    "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY",
    "merchantReference": "MM-H2H-1001",
    "redirectUrl": "https://merchant.example/return",
    "trafficVertical": "TRAFFIC_VERTICAL_OTHER",
    "customerSegment": "CUSTOMER_SEGMENT_FTD",
    "mobileMoneyDetails": {
      "email": "customer@example.com",
      "mobileNumber": "233551234567",
      "operator": "<operator_from_discovery>"
    }
  }'

After creating an H2H mobile-money pay-in, check mobileMoneyDetails.isOtpAuthRequired. When it is true, continue with POST /merchant/api/v1/payins/authorize-otp.

Vouchers

For voucher-based H2H mobile-money pay-ins, include mobileMoneyDetails.voucherPin with the selected operator and customer wallet number. Send voucherPin only for voucher-based routes. See Vouchers for the request shape.

Pay-out

curl -X POST "https://merchants-api.example.com/merchant/api/v1/payouts/create" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currencyCode": "GHS",
    "countryCode": "GH",
    "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY",
    "merchantReference": "MM-PO-1001",
    "trafficVertical": "TRAFFIC_VERTICAL_OTHER",
    "customerSegment": "CUSTOMER_SEGMENT_TRUSTED",
    "mobileMoneyDetails": {
      "mobileNumber": "233551234567",
      "operator": "<operator_from_discovery>",
      "accountName": "Customer Name"
    }
  }'

Send accountName when the selected payout path requires a beneficiary account name.

Request context

Use the same selected market and request context for discovery and payment creation:

• countryCode in discovery and create/init requests
• currencyCode in create/init requests
• paymentMethod
• trafficVertical
• customerSegment

For mobile-money flows, send the selected market countryCode from /catalog in create/init requests.