Skip to main content

Conventions

Last updated: 2026-09-25

JSON representation​

Merchant API JSON follows these rules:

  • Field names are lowerCamelCase in JSON (for example, currencyCode, merchantReference).
  • int64 fields use JSON strings as their canonical encoding (for example, "amount": "10000"). Payment-creation amount fields retain the explicitly documented JSON-integer compatibility exception below.
  • Validation error paths can use snake_case field notation, even when the JSON request field is lowerCamelCase.
  • Localized merchant validations may append a |<messageId> suffix (for example, currency_code|payin.currency.required), while other validation errors may use just the field path (for example, mobile_money_details.operator).

Amounts​

  • amount is expressed in minor units (for example, cents).
  • Send amount as a base-10 integer string containing digits only, for example "amount": "400000".
  • Do not use a decimal point or exponent notation. Representations such as "4000.00", "4e3", 4000.00, and 4e3 are not portable and may be rejected even when mathematically equal to an integer.
  • A lossless JSON integer such as "amount": 400000 remains accepted on payment-creation requests for compatibility. New integrations should use the canonical string form.
  • Keep every payment-creation request body within the supported 1 MiB maximum, regardless of environment. A larger body is outside the public contract and may return HTTP 413; clients must handle that response without retrying the same oversized body.

Enums​

Enum values are represented as strings (the enum constant name), for example:

  • paymentMethod: "PAYMENT_METHOD_BANK_ACCOUNT"
  • status: "PAYMENT_ORDER_STATUS_PENDING"

Timestamps​

Timestamps are RFC3339 / ISO 8601 strings, for example:

  • "2025-10-30T14:35:22.123456Z"

Traffic classification​

Use one of the supported explicit values when your integration knows the classification for the current request:

  • TRAFFIC_VERTICAL_GAMBLING
  • TRAFFIC_VERTICAL_FOREX
  • TRAFFIC_VERTICAL_OTHER

An explicit supported trafficVertical is authoritative for that request. If you omit it or send TRAFFIC_VERTICAL_UNSPECIFIED, the account classification can be applied instead. Use the same explicit value during discovery and payment creation so both operations resolve the same request context.

Idempotency​

Use one unique merchantReference for each intended payment and persist it before sending the request.

For payout creation, merchantReference is the idempotency key. Retrying an equivalent payout request with the same reference returns the existing payout. Reusing that reference with different request data is rejected.

For pay-ins, retry the same endpoint in the same realm with the same reference and an equivalent request. Direct creation reuses the current attempt; hosted initialization replays an unexpired CREATED form, or a PENDING bank-transfer payment. Other methods do not have the pending bank-transfer exception. A retry can repeat the original error, so it is not a guarantee of a successful response. See Pay-in retry rules for supported states and reference reuse after cancellation or expiry.

After an unknown outcome, recover the existing payment by its ID or reference. Do not switch endpoints or generate a fresh reference just because a response was lost. Keep references distinct across pay-ins and payouts so reference lookup remains unambiguous.

Process webhook deliveries idempotently with their Idempotency-Key.