Skip to main content

Mobile money transfer

Last updated: 2026-09-25

Mobile money transfer is an inbound-only payment method. Use it when the account catalog makes the method available for the selected market, then discover a transfer rail with the pay-in operator discovery operation.

It is separate from standard mobile money: the selected operator is a transfer rail code, not the customer's wallet operator.

Hosted pay-in​

  1. Call pay-in operator discovery with paymentMethod=PAYMENT_METHOD_MOBILE_MONEY_TRANSFER and the selected request context.
  2. Initialize the pay-in with the same market, payment method, and one returned rail code in mobileMoneyOperator.
  3. Redirect the customer only when paymentOrder.paymentUrl is returned.
  4. Reconcile the payment after the hosted step through a verified webhook or a payment read.

Hosted initialization does not send mobileMoneyTransferDetails; the customer completes the method-specific step on the hosted page.

Direct pay-in​

  1. Discover the transfer rail as described above.
  2. Create the pay-in with paymentMethod=PAYMENT_METHOD_MOBILE_MONEY_TRANSFER and exactly one mobileMoneyTransferDetails block.
  3. Send the returned rail code as mobileMoneyTransferDetails.operator and the customer's wallet number as mobileMoneyTransferDetails.mobileNumber.
  4. Wait for paymentOrder.mobileMoneyTransferDetails.generationStatus to be succeeded, then render returned instructions in order. Use each instruction's label for display, value as the customer-facing value, and copyable to decide whether to offer a copy action.
  5. Show displayMessage as plain text only for a flow whose customer-facing copy your integration has reviewed. Show expiresAt when present and stop offering payment instructions after it expires. Do not parse the message as payment status or instructions; reconcile the payment status independently.

Do not combine mobile-money-transfer details with a detail block for another payment method. Mobile money transfer is not available for payouts.

Instructions that arrive later​

A successful create can acknowledge the payment before transfer instructions are ready. While generationStatus is processing, read the existing payment with bounded backoff or consume verified webhooks. Honor retryAfter when it is supplied. Do not repeat create to obtain instructions.

GET and webhook PaymentOrder.mobileMoneyTransferDetails can carry updated instructions while the payment remains PENDING. Deduplicate webhook deliveries by Idempotency-Key, not by (paymentId, status), and inspect updatedAt and the details. Keep payment status and instruction availability separate: ready instructions do not mean that money has been received. Stop showing actionable instructions when the payment reaches a terminal result.

API reference​