Mobile money transfer objects
Last updated: 2026-09-25
Direct mobile-money-transfer pay-ins send
mobileMoneyTransferDetails in the create request and can receive an object with
the same JSON field name in the create response.
Request details
| Field | JSON type | Presence | Merchant meaning |
|---|---|---|---|
operator | string | Required (actual) | Transfer rail code returned by pay-in operator discovery |
mobileNumber | string | Required (actual) | Customer mobile wallet number or MSISDN |
The request must not include a detail block for another payment method.
Response details
| Field | JSON type | Presence | Merchant meaning |
|---|---|---|---|
instructions | array | Optional | Ordered customer payment instructions |
expiresAt | string (date-time) or null | Optional | Instruction expiry |
displayMessage | string | Optional | Plain-text customer guidance; do not parse it as payment state or instructions |
A displayMessage alone acknowledges processing; it does not mean transfer
instructions are ready. Use instructions for customer payment actions and
paymentOrder.id or merchantReference to match the payment to your order.
Each instruction contains:
| Field | JSON type | Merchant meaning |
|---|---|---|
key | string | Stable instruction key |
label | string | Display label |
value | string | Customer-facing value |
copyable | boolean | Whether the value is suitable for a copy action; absence means false |
Instruction availability on PaymentOrder
Payment reads and webhooks expose optional mobileMoneyTransferDetails on the
PaymentOrder. This nested object adds the following availability fields to
the response details above:
| Field | JSON type | Merchant meaning |
|---|---|---|
generationStatus | string | Instruction availability; see the states below |
retryAfter | string (date-time) or null | Optional earliest time for another read |
updatedAt | string (date-time) | Time the instruction state was updated, when present |
failureReason | string | Optional public reason when instructions cannot be used |
pending and processing mean instructions are not ready. Display returned
instructions only for succeeded while the payment is pending and any supplied
expiry is still in the future. For failed_retryable, honor retryAfter and
read the existing payment again. For failed_manual_review, contact support
if the condition persists. Treat unknown states as instructions unavailable.
Until instructions are ready, keep reading the existing payment with bounded
backoff or consume verified webhooks; never repeat create just to fetch details.
A same-status PENDING webhook may contain the ready instructions. Terminal
payments omit actionable details. See Webhooks for delivery
idempotency and PaymentOrder for the parent
object.
Related guide: Mobile money transfer.