QR Payments Error Handling

For error response format and general handling, see Key concepts.

Handle QR payment errors by combining internalStatus from the API response with the current phase of the flow. Do not rely on HTTP status alone.


Handling strategy

  1. Parse internalStatus from every non-2xx response.
  2. Map to action: retry, surface to user, or escalate (see tables below).
  3. Never retry 409s — they reflect a state conflict that a retry will not resolve.
  4. For compliance blocks (PAYER_BLOCKED, MERCHANT_BLOCKED, USER_BLOCKED): route to your review/escalation path immediately.
  5. For transient failures (network errors, 5xx): retry with exponential backoff. Do not retry 4xx.

Do not retry on 409. A CONFLICT response means the operation is blocked by state (user validation, existing synthetic, operational limits). Retrying will return the same error until the underlying state changes.


Lock errors

Applies to POST /v2/payment-locks.

Destination decoding

internalStatusHTTPDescriptionAction
PAYMENT_DESTINATION_DECODING_ERROR400Payment destination is invalid or cannot be decodedVerify the scanned QR or destination value
PAYMENT_DESTINATION_AMOUNT400The destination carries no amount (for example a payment key) and none was sent in the lockSend amount in the lock
PAYMENT_DESTINATION_MISSING_AMOUNT400Open-amount destination — amount not yet attachedRetry once the merchant amount is ready
PAYMENT_DESTINATION_EXPIRED409QR expired or inactive at the payment networkRequest a new QR from the merchant
PAYMENT_DESTINATION_NOT_FOUND409Destination not found at the payment networkVerify the destination data
PAYMENT_DESTINATION_DECODING_DISABLED503Decoding service temporarily unavailableRetry later
FAILED_TO_CONNECT_WITH_PROVIDER503Temporary issue with the payment provider — the destination could not be decodedRetry later

Validation

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed request fieldsFix request payload
MISSING_PAYMENT_SENDER400sender object is required but missingInclude sender with exchange, legalId, name, surname
INVALID_COIN400against asset not supportedUse a supported asset — see Coverage
PAYMENT_MAX_AMOUNT400Amount exceeds the maximum allowedLower the amount and retry
PAYER_BLOCKED400Payer is blocked due to compliance restrictionsDo not retry; escalate to compliance
MERCHANT_BLOCKED400Merchant is blocked, by Manteca's compliance team or by your company via POST /v2/blocksDo not retry. If your company blocked it, lift it with DELETE /v2/blocks/:legalId; otherwise escalate to compliance
PAYER_NAME_MISMATCH400Brazil only: the payer's name doesn't match the one already registered for that legalIdDo not retry; verify the payer's legalId, name and surname
PERMISSIONS403Company not enabled for QR payments in this countryContact your integration manager
RATE_LIMITED429Too many payment locks created without executing the payment (rate-limited per user in some countries, today Peru)Execute pending payments before creating new locks; retry later

Execution errors

Applies to POST /v2/synthetics/qr-payment.

Creation errors

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed request fieldsFix request payload
EXPIRED_LOCK400Payment lock has expiredCreate a new lock and retry
NO_FUNDS400Insufficient balanceCheck user balance; surface to user
PAYMENT_LOCK_NF404Lock code not foundVerify paymentCode; create a new lock if needed
OPERATION_BLOCKED409Blocked by limits or policyCheck operational limits; escalate if needed
SYNTHETIC_EXISTS409Synthetic with same externalId already existsFetch existing synthetic instead of creating

Post-execution errors (payment failure codes)

When a QR payment synthetic reaches CANCELLED, the failure reason appears as a code on the failing WITHDRAW stage's errors array — in the same place both in GET /v2/synthetics/{syntheticAnyId} and in the SYNTHETIC_STATUS_UPDATE webhook payload:

"stages": {
    "2": {
        "stageType": "WITHDRAW",
        "errors": ["P4: Payment blocked by receiver"]
    }
}

Each entry is formatted as <code>: <description>. The same code is also delivered as statusMessage on the WITHDRAW_STATUS_UPDATE webhook when the underlying payout reaches CANCELLED.

CodeDescription
P1Generic payment error (reason not classified)
P2Payment rejected by the receiving bank
P3QR expired at payment time
P4Payment blocked on the receiver side (compliance, or the receiving bank/account is not accepting)
P5Invalid QR or destination
P6Invalid PIX key
P7Receiving bank timed out
P8Payment provider error (transient)

How to react:

  • Destination / payer issues — do not blindly retry, surface to the user: P2 (rejected), P4 (blocked on the receiver side), P5 (invalid QR/destination), P6 (invalid PIX key). Retrying the same payment will return the same result; verify the QR, key or destination with the payer.
  • Transient — safe to retry: P3 means the QR timed out between lock and execution — create a new lock and retry promptly. P7 (receiving bank timeout) and P8 (provider error) can be retried with backoff.
  • P1 is unclassified — treat as transient (retry with backoff) but cap the attempts; do not loop indefinitely.

Related pages


Did this page help you?