Skip to main content

Mobile money

Last updated: 2026-08-30

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.

Choose the flow​

FlowMerchant integrationContinue with
Hosted pay-in (H2P)Initialize the payment and redirect the customer to the returned payment pagePay-ins
Direct pay-in (H2H)Discover any required operator, create the payment, and handle the returned customer continuationPay-ins
PayoutDiscover the beneficiary operator, create the payout, and reconcile the resultPayouts

Direct pay-in​

  1. Call the pay-in operator discovery operation with the selected market and request context.
  2. Display operators[].name and reuse the selected operators[].operator exactly as returned.
  3. Create the pay-in with the mobile number and selected operator in the mobile-money detail block.
  4. Treat isOtpAuthRequired as a continuation signal. For an ORANGE payment in a market listed below, collect the customer's OTP and use Merchant API OTP authorization when the create response sets the field to true.
  5. Reconcile the latest status through a verified webhook or a payment read.

Orange OTP continuation​

Deferred OTP is the direct-pay-in contract for public operator ORANGE in these nine markets:

  • Burkina Faso (BF / XOF), Côte d’Ivoire (CI / XOF), Senegal (SN / XOF), and Mali (ML / XOF);
  • Cameroon (CM / XAF), Central African Republic (CF / XAF), and Equatorial Guinea (GQ / XAF);
  • Democratic Republic of the Congo (CD / CDF) and Sierra Leone (SL / SLE).

This list defines the operator flow, not account or realm availability. Use ORANGE only when discovery returns it for the current account and realm. There is no separate Orange OTP activation.

  1. Create the direct pay-in with PAYMENT_METHOD_MOBILE_MONEY.
  2. When the create response returns mobileMoneyDetails.isOtpAuthRequired: true, ask the customer to follow their mobile money provider's instructions to get or generate the one-time code.
  3. Within 15 minutes of payment creation, send the payment ID and OTP to POST /merchant/api/v1/payins/authorize-otp.
  4. Treat an accepted OTP as continuation, not final payment success. The payment can remain PENDING, so continue reconciliation.

There is no universal fixed OTP exposed by the Merchant API for this flow. If the OTP is rejected, the customer can provide a corrected OTP before the 15-minute deadline. If authorization returns HTTP 503 / UNAVAILABLE, retry after the Retry-After delay instead of submitting in a tight loop.

See Authorize pay-in OTP for the request, response, and error contract.

Do not display displayMessage by default. Enable it only for flows whose customer-facing copy you have reviewed, and render it as plain text. Do not parse it as payment status, a failure reason, or payment instructions. Store it from the create response if you need to keep showing approved copy because later payment reads do not include the mobile-money response details.

For a voucher-based route, follow Vouchers and send a voucher PIN only when that route requires one.

Hosted pay-in​

Call pay-in operator discovery when the selected standard mobile-money market requires an operator. Send the returned public code in mobileMoneyOperator during initialization; omit it only when discovery and the selected market do not require an operator. The customer completes the remaining method-specific step on the hosted page.

Redirect only when paymentOrder.paymentUrl is returned. Treat the customer return as navigation, not payment confirmation.

Payout​

  1. Call the payout operator discovery operation for the selected market and request context.
  2. Reuse the selected operator exactly as returned when you create the payout.
  3. Send a beneficiary account name when the selected payout path requires one.
  4. Reconcile the latest status; request acceptance is not a final payout outcome.

Request context​

Use the same countryCode, paymentMethod, trafficVertical, and customerSegment values for discovery and payment creation. Use the selected market currency for the payment request.

Discovery responses use public CAPS codes. Treat them as opaque and case-sensitive: do not map, lowercase, rename, or hard-code them as a fixed enum. Store and send only the code returned for the current request context.

For the separate inbound-only transfer method, use Mobile money transfer.

API reference​