Errors

Last updated: 2026-05-22

Non-2xx responses use a google.rpc.Status-compatible shape:

{
  "code": 3,
  "message": "currencyCode is required",
  "details": []
}

Common code values:

code	Meaning
3	INVALID_ARGUMENT (validation)
5	NOT_FOUND
7	PERMISSION_DENIED
13	INTERNAL
16	UNAUTHENTICATED

Validation error example (field violations)

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "currency_code|payin.currency.required",
          "description": "currencyCode is required"
        },
        {
          "field": "amount|payin.amount.required",
          "description": "amount must be greater than 0"
        }
      ]
    }
  ]
}

Use fieldViolations to map API validation errors to specific form fields on your side (for example highlight currencyCode input when currency_code|payin.currency.required is returned).

Nested field violations use protobuf/snake_case paths. Localized merchant validations may append a |<messageId> suffix, while other validation errors may use just the field path. For example, a missing payout operator can be reported as mobile_money_details.operator, which maps to the JSON field mobileMoneyDetails.operator.

Outcome vs transport status

• Validation/auth/system issues return non-2xx with rpc.Status.
• Payment outcome is carried by paymentOrder.status (often in HTTP 200 responses).
• For mobile-money pay-ins, missing mobileMoneyDetails or mobileMoneyDetails.mobileNumber is a validation error and returns non-2xx.
• For operator-aware mobile-money pay-ins and payouts, a missing required mobileMoneyDetails.operator is a validation error and returns non-2xx.
• For voucher-based mobile-money pay-ins, send mobileMoneyDetails.voucherPin when the selected route requires voucher collection.