Core objects
Last updated: 2026-05-22
PaymentOrder (merchant view)
All merchant-facing responses and webhooks return the same PaymentOrder shape.
| Field | Type | Notes |
|---|---|---|
id | string (UUID) | Payment order ID |
merchantReference | string | Your reference (not enforced unique by the API; treat as unique on your side) |
paymentMethod | string (enum) | See Payment methods |
type | string (enum) | PAYMENT_ORDER_TYPE_PAYMENT_IN or PAYMENT_ORDER_TYPE_PAYMENT_OUT |
status | string (enum) | See status lifecycle below |
amount | string (int64) | Minor units |
currencyCode | string | ISO 4217 currency code |
paymentUrl | string | Optional payment URL. Some H2P and H2H pay-in flows return it |
redirectUrl | string | Optional. Merchant return URL (pay-ins) |
failureReason | string | Present for negative states |
failureReasonCode | string (int64) | Present with failureReason |
createdAt | string (date-time) | UTC |
updatedAt | string (date-time) | UTC |
trafficVertical | string (enum) | Traffic category used for payment selection and compliance |
customerSegment | string (enum) | Request-context value. May be echoed back in merchant-visible objects |
marketDetails | object | Optional selected-market details for the stored payment when returned |
Merchant responses include the fields needed to reconcile and display your payment flow.
Request context dimensions
trafficVertical values:
TRAFFIC_VERTICAL_UNSPECIFIEDTRAFFIC_VERTICAL_GAMBLINGTRAFFIC_VERTICAL_FOREXTRAFFIC_VERTICAL_OTHER
customerSegment values:
CUSTOMER_SEGMENT_UNSPECIFIEDCUSTOMER_SEGMENT_FTDCUSTOMER_SEGMENT_TRUSTEDCUSTOMER_SEGMENT_VIP
isGambling is kept for legacy compatibility in requests. For new integrations, use trafficVertical.
Payment status lifecycle
PAYMENT_ORDER_STATUS_CREATEDPAYMENT_ORDER_STATUS_PENDINGPAYMENT_ORDER_STATUS_COMPLETED(terminal)PAYMENT_ORDER_STATUS_FAILEDPAYMENT_ORDER_STATUS_CANCELLED(terminal)PAYMENT_ORDER_STATUS_EXPIRED(terminal)
PENDING -> PENDING updates are valid and can be sent more than once while a payment is pending. A late provider confirmation can also correct FAILED to COMPLETED, so process webhook updates idempotently and use the latest accepted paymentOrder.status for reconciliation.
Market details
When returned, marketDetails describes the selected market for the stored payment. Treat it as checkout guidance for that payment, not as a global support matrix.
| Field | Type | Notes |
|---|---|---|
countryCode | string | ISO 3166-1 alpha-2 country code of the selected market |
mobileMoney.supported | boolean | Whether mobile money is supported for the stored route |
mobileMoney.operatorRequired | boolean | Whether payer/operator selection is required before processing |
mobileMoney.operatorLocked | boolean | Whether the operator was already selected and stored on the payment |
mobileMoney.operator | string | Stored operator code when operatorLocked = true |
mobileMoney.operators[] | array | Checkout-safe operator options for payer selection |
mobileMoney.unavailableReason | string | Reason when mobile-money details are unavailable or unsupported |
mobileMoney.operators[].operator is a machine-readable code. Reuse it exactly if your checkout flow asks the payer to select an operator.
Failure reasons
When a payment reaches a negative state (FAILED, CANCELLED, EXPIRED), the API may set:
failureReason(string)failureReasonCode(stringified int)
failureReason | failureReasonCode | Meaning |
|---|---|---|
internal_error | 1 | Processing error |
unknown | 2 | Unknown reason |
declined | 3 | Declined by customer or payment partner |
cancelled_by_user | 4 | User cancelled |
invalid_request | 5 | Invalid or unsupported request parameters |
insufficient_funds | 6 | Insufficient funds (customer or merchant, context-dependent) |
expired_payment | 7 | Payment session expired |
expired_payment_form | 8 | Payment form expired |
suspected_fraud | 9 | Suspected fraud |
provider_unavailable | 10 | Temporary processing unavailability |
amount_out_of_range | 11 | Amount outside supported limits |
MerchantBalance
Returned by GET /merchant/api/v1/balances.
| Field | Type | Description |
|---|---|---|
accountId | string (UUID) | Ledger account ID |
accountType | string (enum) | Account type |
currencyCode | string | ISO 4217 |
amount | string (int64) | Signed minor units |
amount is signed. A negative value means the merchant has a net liability/owed amount for that account/currency.
Bank
Returned by bank listing endpoints.
| Field | Type |
|---|---|
code | string |
name | string |
MobileMoneyOperator
Returned by GET /merchant/api/v1/payins/mmo and GET /merchant/api/v1/payouts/mmo. Reuse operator exactly as returned when initializing or creating operator-aware mobile-money payments.
| Field | Type | Notes |
|---|---|---|
operator | string | Machine-readable operator code to send back in operator-aware mobile-money requests |
name | string | Human-readable operator name for merchant UI/display |