Error Codes

API errors are returned with a consistent standard error response. Raw bank error codes (bank transaction/result codes) are not surfaced to the customer; you only see the stable codes below.

Standard error response

{
  "error": {
    "code": "terminal_not_allowed",
    "message": "Terminal is not allowed for this partner.",
    "traceId": "trc_9f12ab"
  }
}

Field	Description
`code`	Stable, machine-readable error code (catalog below).
`message`	Human-readable description.
`traceId`	A trace identifier to share in support requests.

HTTP status mapping

Validation and business-rule violations → 4xx (e.g., 400, 409, 422).
Authentication failure → 401.
Every error response carries an error.code and a traceId.

Code catalog

Code	Meaning
`duplicate_partner_tx_code`	An active/successful payment already exists with the same `partnerTxCode`.
`terminal_not_allowed`	The terminal does not belong to the partner or is inactive.
`amount_limit_exceeded`	The amount is outside the allowed min/max range.
`installment_not_allowed`	The card is not eligible for installments or the terminal has no installment permission.
`payment_not_refundable`	The payment is not in a refundable state.
`refund_amount_exceeds_remaining`	The requested refund amount exceeds the remaining refundable balance.
`refund_not_yet_available`	Same-day partial refund: available after day-end.
`refund_in_progress`	A pending refund already exists for this payment (single-flight rule).

Handoff errors

The codes below occur during Card Handoff when the paymentRef sent to the handoffUrl is not valid. The remedy is always the same: create a new cardless payment (POST /v1/payments), then start the handoff again with the new paymentRef/handoffUrl it returns.

Code	HTTP	Meaning
`payment_ref_invalid`	`404`	The `paymentRef` is invalid/unknown.
`payment_ref_expired`	`404`	The `paymentRef` has expired.
`payment_prepare_already_started`	`409`	3D has already been started for this `paymentRef` (single-use).