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
- Parse
internalStatusfrom every non-2xx response. - Map to action: retry, surface to user, or escalate (see tables below).
- Never retry 409s — they reflect a state conflict that a retry will not resolve.
- For compliance blocks (
PAYER_BLOCKED,MERCHANT_BLOCKED,USER_BLOCKED): route to your review/escalation path immediately. - For transient failures (network errors, 5xx): retry with exponential backoff. Do not retry 4xx.
Do not retry on 409. A
CONFLICTresponse 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
internalStatus | HTTP | Description | Action |
|---|---|---|---|
PAYMENT_DESTINATION_DECODING_ERROR | 400 | Payment destination is invalid or cannot be decoded | Verify the scanned QR or destination value |
PAYMENT_DESTINATION_AMOUNT | 400 | The destination carries no amount (for example a payment key) and none was sent in the lock | Send amount in the lock |
PAYMENT_DESTINATION_MISSING_AMOUNT | 400 | Open-amount destination — amount not yet attached | Retry once the merchant amount is ready |
PAYMENT_DESTINATION_EXPIRED | 409 | QR expired or inactive at the payment network | Request a new QR from the merchant |
PAYMENT_DESTINATION_NOT_FOUND | 409 | Destination not found at the payment network | Verify the destination data |
PAYMENT_DESTINATION_DECODING_DISABLED | 503 | Decoding service temporarily unavailable | Retry later |
FAILED_TO_CONNECT_WITH_PROVIDER | 503 | Temporary issue with the payment provider — the destination could not be decoded | Retry later |
Validation
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed request fields | Fix request payload |
MISSING_PAYMENT_SENDER | 400 | sender object is required but missing | Include sender with exchange, legalId, name, surname |
INVALID_COIN | 400 | against asset not supported | Use a supported asset — see Coverage |
PAYMENT_MAX_AMOUNT | 400 | Amount exceeds the maximum allowed | Lower the amount and retry |
PAYER_BLOCKED | 400 | Payer is blocked due to compliance restrictions | Do not retry; escalate to compliance |
MERCHANT_BLOCKED | 400 | Merchant is blocked, by Manteca's compliance team or by your company via POST /v2/blocks | Do not retry. If your company blocked it, lift it with DELETE /v2/blocks/:legalId; otherwise escalate to compliance |
PAYER_NAME_MISMATCH | 400 | Brazil only: the payer's name doesn't match the one already registered for that legalId | Do not retry; verify the payer's legalId, name and surname |
PERMISSIONS | 403 | Company not enabled for QR payments in this country | Contact your integration manager |
RATE_LIMITED | 429 | Too 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
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed request fields | Fix request payload |
EXPIRED_LOCK | 400 | Payment lock has expired | Create a new lock and retry |
NO_FUNDS | 400 | Insufficient balance | Check user balance; surface to user |
PAYMENT_LOCK_NF | 404 | Lock code not found | Verify paymentCode; create a new lock if needed |
OPERATION_BLOCKED | 409 | Blocked by limits or policy | Check operational limits; escalate if needed |
SYNTHETIC_EXISTS | 409 | Synthetic with same externalId already exists | Fetch 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.
| Code | Description |
|---|---|
P1 | Generic payment error (reason not classified) |
P2 | Payment rejected by the receiving bank |
P3 | QR expired at payment time |
P4 | Payment blocked on the receiver side (compliance, or the receiving bank/account is not accepting) |
P5 | Invalid QR or destination |
P6 | Invalid PIX key |
P7 | Receiving bank timed out |
P8 | Payment 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:
P3means the QR timed out between lock and execution — create a new lock and retry promptly.P7(receiving bank timeout) andP8(provider error) can be retried with backoff. P1is unclassified — treat as transient (retry with backoff) but cap the attempts; do not loop indefinitely.
Related pages
- Preview a payment — lock request details and
senderrequirements - Make a payment — execution request and response
- Payment lifecycle — status transitions and monitoring
Updated 26 days ago