Errors and Decline Codes
Card acquiring errors follow the error format of the rest of the API: an HTTP status and a JSON body with an error field, sometimes with an extraInfo that says more.
{ "error": "InvalidFieldError: device.ipAddress is invalid" }
Field names in error messages are the names of the request, in camelCase (payerEmail, saveCard.customerReference). Match on the HTTP status and the message prefix (InvalidFieldError, NotFoundError and so on): the wording after the prefix can be improved without notice. For a payment that ended BLOCKED, DECLINED or ERROR, or a refund or a settlement that ended FAILED, match on failureCode, which is stable.
Decline buckets
A declined payment event and a read of the payment carry declineBucket, so you know what to tell your customer. The synchronous answer of POST /payments carries failureCode but not declineBucket: take it from the webhook or from GET /payments/{payment-id}. The customer never sees the reason on the hosted page, by design.
declineBucket | Meaning | What to do |
|---|---|---|
RETRYABLE | The refusal may pass if the customer tries the same card later: insufficient funds, "do not honor", or a new card the bank has not unlocked yet (first use). | Offer a new attempt (a new quote) after the customer had the chance to fix the cause, such as adding funds or unlocking the card in the bank's app. |
TERMINAL | The same card will not pass. | Ask for another card. |
RETRYABLE means "may pass if tried later", not "retry now": do not repeat the charge in a loop. Every attempt is a card tried, and a caller that repeats at once only collects more declines. Avenia never retries a declined payment on its own, and you should not retry without the customer either.
On the hosted page a decline is per attempt: the customer may try another card on the same payment, which can still be captured. Offer a new attempt with a new quote only after the session has ended without a capture: see Trying another card.
A card reported lost, stolen or to be picked up is always TERMINAL and ends DECLINED with failureCode FRAUD_DECLINED. A decline Avenia cannot place is TERMINAL: asking for another card is the safe answer. declineBucket is "" on every event that is not a decline.
Sub-statuses and failure codes
subStatus refines a terminal status:
status | subStatus | Meaning |
|---|---|---|
DECLINED | ISSUER_DECLINED | The customer's bank refused. |
DECLINED | FRAUD_DECLINED | Refused by fraud screening, or by an issuer that reports the card lost, stolen or to be picked up. |
ERROR | INTERNAL_ERROR | Every ERROR: the authorization did not complete, on our side or at the acquirer. |
EXPIRED | CHECKOUT_ABANDONED | The customer left without paying. |
EXPIRED | CAPTURE_WINDOW_LAPSED | Our failure to capture in time; the customer was not charged. Tell Avenia. |
failureCode names the reason a payment ended BLOCKED, DECLINED or ERROR. It is on the answers that return the payment (POST /payments, the saved-card charge, GET /payments/{payment-id}) and on the payment events, and is "" for any other status. Codes are only ever added, never renamed or removed: treat an unknown one like the status it came with.
status | failureCode | Meaning |
|---|---|---|
BLOCKED | USER_BLOCKED | Your account (or the sub-account) is blocked, or card acquiring was turned off for it after the sale was opened. Refused before the issuer was called. Contact Avenia if unexpected. |
DECLINED | ISSUER_DECLINED | The customer's bank refused. declineBucket says whether the same card may work later. |
DECLINED | FRAUD_DECLINED | Refused by fraud screening, or because the issuer reports the card lost, stolen or to be picked up; always TERMINAL. |
DECLINED | DECLINED | Declined with no finer reading. |
ERROR | INTERNAL_ERROR | The authorization did not complete, on our side or at the acquirer; the code does not say which. No money moved. Offer a new attempt, and contact Avenia if it repeats. |
Refund failure codes
A refund's failureCode names why it ended FAILED, when the cause is one you can act on. It is on each refund in refunds when you read the payment, and on the refund events. It is "" on any other refund, including one a person rejected, one whose approval expired and one the acquirer refused. Codes are only ever added, never renamed or removed.
failureCode | Meaning |
|---|---|
PAYMENT_NOT_REVERSIBLE | The refund waited for approval while its payment stopped being reversible (a chargeback landed): sending it would have paid the cardholder twice. Nothing was sent. |
Settlement failure codes
A settlement's failureCode names why it ended FAILED. It is on GET /settlements/{settlement-id} and in the settlement events, and is settlementFailureCode, beside settlementStatus, on statement lines and early settlement reads. It is "" on every status but FAILED. A settlement that fails sends no event: you learn of it by reading the settlement. Codes are only ever added, never renamed or removed: treat an unknown one like INTERNAL_ERROR.
failureCode | Meaning | When |
|---|---|---|
INTERNAL_ERROR | The payout did not land, for a cause on Avenia's side. Nothing was paid; there is nothing for you to change. Contact Avenia. | A settlement ends FAILED: the transfer to the payout wallet was refused before anything was sent, or was found not to have landed. |
HTTP errors
| HTTP | error (examples) | What to do |
|---|---|---|
| 400 | card data must be encrypted before it reaches this API | A readable card number reached the API: the request bypassed the relay, or the card is outside card.encrypted. Send it to the relay URL: see Server-to-Server Payments. |
| 400 | InvalidBodyError: could not parse body data | Invalid JSON, a string where a number goes (expirationMonth), an amount or rate that is not a number ("ten", ""), or a body over 4 KB. With "extraInfo": "content after the JSON object": send one JSON object and nothing after it. |
| 400 | InvalidFieldError: card.encrypted.<field> is invalid, with "extraInfo": "card fields must arrive encrypted by the relay" | The card field arrived unencrypted or damaged. Check that the request went through the relay and that the field sits under card.encrypted. |
| 400 | InvalidFieldError: device.<field> is invalid | Fix that field of the device block. |
| 400 | InvalidFieldError: <field> is invalid | Fix the named field. extraInfo can say why: a decimal that is not plain (exponent notation, more than 20 digits before the point or 18 after), an amount with more than 2 decimal places, above your limit or below the minimum, or an externalId longer than 68 characters. |
| 400 | InvalidFieldError: successUrl is invalid (or cancelUrl) | The URL is not https, or not on your registered domains. Nothing was charged. |
| 400 | InvalidFieldError: <field> is invalid, with "extraInfo": "not a field of this request" | The body has a field the request does not take. Remove it. |
| 400 | InvalidFieldError: <key> is invalid on a GET, or on any route with a query key it does not take | A query parameter the route does not take. Only the parameters listed for each route, and subAccountId, are accepted. |
| 400 | InvalidFieldError: subAccountId is invalid | subAccountId is not a UUID. |
| 400 | InvalidFieldError: saveCard.customerReference is invalid or saveCard.cardholderConsented is invalid | See Saved Cards. |
| 400 | InvalidFieldError: savedCard.savedCardId is invalid, savedCard.customerReference is invalid, card is invalid or saveCard is invalid | See Saved Cards. |
| 400 | InvalidFieldError: beneficiaryWalletId is invalid | Not one of your beneficiary wallets (not a UUID, unknown, or another account's). Name one of the selling account's wallets: see settling a sale to a wallet. |
| 400 | InvalidFieldError: beneficiaryWalletId is invalid | The wallet's chain is not the chain of the quote's output. Name a wallet on that chain, or quote the sale again for the wallet's chain. |
| 400 | InvalidFieldError: beneficiaryWalletId is invalid | No beneficiaryWalletId, and the quote's output is on a blockchain. Name a wallet on that chain, or use a quote whose output is INTERNAL to be paid to your account's balance. |
| 400 | InvalidFieldError: beneficiaryWalletId is invalid, with "extraInfo": "the destination sub-account is hidden" | The wallet is the wallet of another account of your workspace that is hidden from your dashboard. Name another wallet. |
| 400 | InvalidFieldError: beneficiaryWalletId is invalid | A beneficiaryWalletId with a quote whose output is INTERNAL. Leave it out: the sale is paid to your account's balance. |
| 400 | InvalidFieldError: quoteToken is invalid | The quoteToken is missing, unreadable, expired, another account's or not a card sale quote, the card price changed since the quote, its markup is above your workspace's cap, or its amount is too small to settle. extraInfo says which: see the quote token. Quote the sale again. |
| 400 | InvalidFieldError: amount is invalid, with "extraInfo": "not a field of this request" | A sale has no amount: its amount is the quote's inputAmount. Remove the field. |
| 400 | InvalidFieldError: installments is invalid | More installments than your maximum, or installments on a debit card. |
| 400 | only BRL is accepted as the sale currency | Send currency as BRL. |
| 400 | the X-API-IdempotencyKey header is required on this route | Add the header (refunds and dispute evidence). |
| 400 | an early settlement needs an idempotency key | Add the X-API-IdempotencyKey header to the early settlement. |
| 400 | prepaid cards are not accepted | Ask for another card. |
| 400 | confirmAmount is not this dispute's amount: nothing was accepted | Send the dispute's amount. |
| 401 | UnauthorizedError | Check key id, timestamp (milliseconds, clock in sync), signature and IP: see Authentication. On the payment route, also: the payments key's allowlist holds the relay's addresses, the signed body is the canonical body without card.encrypted, and no key is repeated ignoring case. |
| 402 | the payment was refused | Refused by Avenia, for example by its risk rules. Offer another card, with a new quote. A payment that failed on our side or at the acquirer answers 500, not 402. |
| 403 | ForbiddenError | Refunds, dispute decisions and early settlements need an admin access, or the sub-account is blocked for this access. |
| 404 | NotFoundError: subAccountId not found | The sub-account is not one of yours. |
| 404 | NotFoundError: account not found | The account (or the sub-account named in subAccountId) has no card acquiring configuration. Contact Avenia. |
| 404 | NotFoundError: payment not found, settlement not found, dispute not found, saved card not found | Wrong id, or it belongs to another account or sub-account. |
| 404 | settling on demand exists only in the sandbox; here settlements run on their own schedule, simulating a refund decision exists only in the sandbox; here a person decides | These routes exist only in the sandbox. |
| 409 | an authorization for this quoteToken is already running | Wait a few seconds and repeat. |
| 409 | this quoteToken has already been paid | Quote again for a new payment. |
| 409 | this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new one | A quote token opens one sale, on one entry point. Repeat the same request, or quote again. This is also the answer when you correct a request that was refused with a 400 after its session was created (installments, a prepaid card, an amount above a limit): quote again and send the corrected request with the new quoteToken. |
| 409 | QUOTE_EXPIRED: the quote of this sale has expired; quote the sale again | The payment started after its quote's 5 minutes; nothing was charged. Match the QUOTE_EXPIRED: prefix. Quote again and send the new quoteToken. On the hosted page the customer gets 409 {"code": "QUOTE_EXPIRED", "message": "this price has expired -- please return to the store and start the purchase again"}. |
| 409 | this checkout session was cancelled | The session was cancelled while its payment was being authorized; nothing was charged. |
| 409 | an authentication for this quoteToken is already in progress, on payment <id>, and it cannot be restarted from here | A 3D Secure challenge is open for this sale. Reconcile with that payment. |
| 409 | the account is blocked and cannot accept payments | Your account (or the sub-account) is blocked for acquiring. Contact Avenia. |
| 409 | the account is not ready to accept payments yet | The account's acquiring set-up is not complete. Contact Avenia. |
| 409 | the reversal is larger than what is left of this payment, this payment cannot be reversed in its current state | See Refunds. |
| 409 | Refund approval: the request to approve this refund expired; the refund was closed refused and nothing was sent, the payment no longer has this much left to refund; nothing was approved, the payment can no longer be refunded; the waiting refund was closed and nothing was sent | Nothing was sent to the customer. |
| 409 | Saved-card and dispute errors | See Saved Cards and Card Disputes. |
| 409 | Early settlement errors | See Early settlements. |
| 429 | checkout session creation limit reached for this account; retry later | Slow down: see the limits below. |
| 429 | this payment was read from the provider a moment ago; retry shortly to get the address for the authentication in progress on payment <id> | Repeat after a few seconds. |
| 500 | InternalError: please contact us | Something failed on our side or at the acquirer; the answer never says which. Repeat once with the same quoteToken and body (payments) or X-API-IdempotencyKey (refunds, early settlements); if it persists, send Avenia the time and the reference. A refund: see When a refund does not go through. A contest: see Card Disputes errors. |
Retry policy. It is safe to repeat any 5xx or a timeout with the same quoteToken and body (payments) or the same X-API-IdempotencyKey (refunds, evidence, early settlements): you get the existing result back, never a second charge or refund. Do not repeat a 4xx without fixing the request.
Limits
| Limit | Sandbox value |
|---|---|
| Amount per payment | R$ 5,000.00 ("5000.00"). Above it, the payment is refused with 400 InvalidFieldError: amount is invalid. Your account also has a monthly volume limit. |
| Payments per seller | 60 per hour and 500 per day (UTC day). Above it: 429. |
Payments per quoteToken | 1 |
| Charges of saved cards | R$ 5,000.00 per charge, 60 per hour, 500 per day. |
| Installments | Up to 12, credit cards only. In production your contract decides. |
| Request body | 4 KB (a dispute evidence upload: about 1.1 MB). |
| Schedule and statement reads | At most 366 days per read, 500 entries per page (100 by default). |
| Webhook URLs per account | 3 |
| Request timestamp tolerance | 60 seconds, either way. |
| Checkout session life | 5 minutes: the life of its quote. |