Skip to main content

Conventions

Last updated: 2026-07-15

JSON representation​

Merchant API JSON follows these rules:

  • Field names are lowerCamelCase in JSON (for example, currencyCode, merchantReference).
  • int64 fields are encoded as JSON strings (for example, "amount": "10000").
  • 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).
  • It is transmitted as a string in JSON.

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"

Idempotency​

Use one unique merchantReference for each intended payment and persist it before sending the request. Create operations do not guarantee automatic duplicate suppression.

If a response is lost or times out, reconcile the existing payment by its ID or merchant reference before deciding whether to create a new attempt. Process webhook deliveries idempotently with their Idempotency-Key.