Skip to main content

Payment methods

Last updated: 2026-05-22

Payment methods are selected by the paymentMethod enum. Available options depend on the operation and the discovery results for your request context.

Enum values​

  • PAYMENT_METHOD_BANK_ACCOUNT
  • PAYMENT_METHOD_BANK_TRANSFER
  • PAYMENT_METHOD_MOBILE_MONEY
  • PAYMENT_METHOD_CARD (enum exists, rejected by the API for merchant pay-in/pay-out)
  • PAYMENT_METHOD_TEST (test environments only)

Availability by operation​

Pay-in

  • PAYMENT_METHOD_BANK_ACCOUNT
  • PAYMENT_METHOD_BANK_TRANSFER
  • PAYMENT_METHOD_MOBILE_MONEY
  • PAYMENT_METHOD_TEST (non-production only)
  • PAYMENT_METHOD_CARD (rejected)

Pay-out

  • PAYMENT_METHOD_BANK_ACCOUNT
  • PAYMENT_METHOD_MOBILE_MONEY
  • PAYMENT_METHOD_TEST (non-production only)
  • PAYMENT_METHOD_BANK_TRANSFER (rejected)
  • PAYMENT_METHOD_CARD (rejected)

Merchant discovery​

GET /merchant/api/v1/catalog is the availability snapshot for the countries, currencies, and method families returned for your account.

Each markets[] item contains:

  • countryCode
  • currencyCode
  • methodsIn
  • methodsOut

methodsIn and methodsOut use lower-case catalog tokens such as mobile_money, bank_transfer, and bank_account.

These are discovery tokens. Order requests still use the PAYMENT_METHOD_* enum literals.

Example:

  • Catalog discovery: methodsIn: ["mobile_money"]
  • Order request: "paymentMethod": "PAYMENT_METHOD_MOBILE_MONEY"

After you choose a market and method family from /catalog:

  • Call GET /merchant/api/v1/payins/banks when the selected inbound method needs a bank list.
  • Call GET /merchant/api/v1/payins/mmo when the selected inbound mobile-money method needs operator detail.
  • Call GET /merchant/api/v1/payouts/banks when the selected outbound method needs a bank list.
  • Call GET /merchant/api/v1/payouts/mmo when the selected outbound method needs operator detail.

Reuse the selected countryCode and currencyCode consistently across discovery and create/init requests.

For POST /merchant/api/v1/payins/initialize and POST /merchant/api/v1/payins/create, countryCode is required for mobile-money pay-ins and country-scoped currencies such as NGN, KES, GHS, ZAR, XAF, and XOF. For POST /merchant/api/v1/payouts/create, countryCode is required for those country-scoped currencies. Send the selected market countryCode from /catalog.

For pay-ins and payouts, send the same request context you plan to use operationally when calling discovery and order endpoints. Include customerSegment when your integration classifies traffic by segment.

For mobile-money pay-ins and pay-outs, treat the returned operator as an opaque discovery value and reuse it exactly as returned in mobileMoneyOperator or mobileMoneyDetails.operator. Voucher-based mobile-money pay-ins also use mobileMoneyDetails.voucherPin.

For mobile-money integration guidance, use Mobile money and Vouchers. For market coverage and operator discovery, use Coverage and Mobile money operators.

Use Flows for the recommended request sequence and Endpoints for the exact request and response shapes.

What to persist in your system​

Store these values for reconciliation and support workflows:

  • paymentOrder.id
  • merchantReference
  • status
  • amount
  • currencyCode
  • paymentMethod
  • createdAt, updatedAt

Sandbox-only: PAYMENT_METHOD_TEST​

PAYMENT_METHOD_TEST is allowed only in non-production environments.

Request payload:

"testDetails": {
  "status": "pending",
  "providerError": "optional simulated failure message",
  "error": "optional hard error (forces request failure)"
}

Supported test statuses and resulting payment statuses:

testDetails.statusResulting paymentOrder.status
pendingPAYMENT_ORDER_STATUS_PENDING
completedPAYMENT_ORDER_STATUS_COMPLETED
failedPAYMENT_ORDER_STATUS_FAILED
cancelledPAYMENT_ORDER_STATUS_CANCELLED
expiredPAYMENT_ORDER_STATUS_EXPIRED
createdPAYMENT_ORDER_STATUS_CREATED (not valid for create-time transition; avoid)

Additional behavior:

  • If error is set, the request returns an error instead of creating a test payment.
  • providerError adds a failure message to the simulated result.

For existing test payments in non-production environments, use POST /merchant/api/v1/payment/{id}/simulate to simulate a status transition after the order has been created. Supported target statuses are completed, expired, and declined.