Skip to main content

Ticket Lifecycle and Failures

A ticket moves through a deposit phase (Avenia receives the input) and a delivery phase (Avenia sends the output). This page lists every status, what happened to the money when a ticket fails, and what each failureCode means.

Statuses​

StatusFinal?Meaning
UNPAIDNoCreated, waiting for the input. Stays UNPAID after expiration — see Expired tickets.
PROCESSINGNoThe input was received and the operation is running.
ON-HOLDNoPaused for compliance review during the deposit, before it is settled.
PAIDYesDelivered. For BRL PIX payouts, settled at the beneficiary's institution.
FAILEDYesThe operation didn't complete. See the table below for where the funds are.
PARTIAL-FAILEDYesOne phase completed and a later one failed. The funds are in your Avenia balance — see the table below.
CANCELEDYesYou canceled it while it was UNPAID. No webhook is sent for a cancellation.

Final statuses normally send a TICKET-COMPLETE webhook (a cancellation never does). Always read status and failureCode before marking the operation as done, and don't rely on webhooks alone: if a ticket hasn't reached a final status when you expect it, read it with GET /v2/account/tickets/{id}. The event list is in Webhook Events.

Where the money is when a ticket fails​

What failedStatusWebhookThe funds
A BRL PIX deposit was rejected (limits, compliance, verification)FAILEDDEPOSIT-FAILEDRefunded in full to the payer's account. reason reads Refund in progress. and later includes the refund E2E ID.
A deposit was rejected (for example by a compliance review) but can't be returned to the senderPARTIAL-FAILEDDEPOSIT-SUCCESS, DELIVERY-PROCESSING, then DELIVERY-PARTIAL-FAILEDCredited to your Avenia balance — for most operations as Avenia's token for the output currency (BRLA for a BRL payout, USDC for USD, EURC for EUR, the same token for a crypto output); for COP, ARS, MXN and SWIFT payouts, the full input amount as the token of the input currency (for example BRLA for a PIX input).
A blockchain or INTERNAL input failed (signature, allowance, balance)FAILEDDEPOSIT-FAILEDNothing was debited.
The payout was refused or failed after the input was debited or convertedPARTIAL-FAILEDDELIVERY-PARTIAL-FAILEDCredited to your Avenia balance, in the currency the operation had reached (for example USDC in a BRL → USD payout). Not sent back on-chain.
An unexpected errorFAILEDDEPOSIT-FAILED or DELIVERY-FAILEDfailureCode is INTERNAL_ERROR. If it happens during delivery, the input may already have been debited: contact support with the ticket id.

A payout that the receiving institution returns after it was paid doesn't change the original ticket, which stays PAID. A new incoming ticket credits the amount back; its externalId is the original ticket's ID. See Reversals after a PIX was paid.

failureCode reference​

Branch on failureCode. failureReason is a human-readable explanation for logs and support; its wording can change, so don't parse it. Every code, with its status and where the funds are, is listed in Ticket Failure Codes. The tables below cover the codes you can act on, with the failureReason text you see today for each.

Most failed deliveries have a failureReason of the form ticket failed partially: <reason> - tokens returned to user's wallet, where "wallet" means your Avenia balance. A deposit rejected by a check that couldn't be returned to the sender ends PARTIAL-FAILED with its own message instead; in that case the funds are in your balance, not returned to the sender.

Deposit​

failureCodefailureReason todayWhat to do
LIMIT_EXCEEDEDuser does not have enough limitThe account's limit doesn't cover the amount. Ask for a higher limit or split the operation. Check them with Get Account Limits.
THIRD_PARTY_DEPOSITthird party deposit is not allowed for this userThe payer isn't the account holder and the account doesn't accept third-party deposits. Pay from the holder's own bank account.
INTERNAL_ERRORdeposit could not be verified, funds returnedThe checks couldn't be completed. On a FAILED ticket the deposit was returned to the payer; on a PARTIAL-FAILED ticket it is in your balance. Try again later.
SENDER_BLOCKED_BANK_INSTITUTION, SENDER_BLOCKED_TAX_IDsender bank institution is blocked, sender tax id is blockedThe sender can't pay this account. Use another sender.
USER_BLOCKEDuser is blocked, funds returned. Contact compliance@avenia.ioContact compliance.
COMPLIANCE_REJECTED / COMPLIANCE_UNDER_REVIEWkyb verification rejected / kyb verification pending, kyb verification not completed in timeThe account's compliance review did not clear. Contact compliance@avenia.io.
FEE_ACCOUNT_INSUFFICIENT_BALANCEinsufficient balance on the fee account, please top it upYour fee account can't cover the fees. Top it up and create a new ticket.
COMPLIANCE_REJECTEDCompliance messages such as Transaction rejected…Permanent for this counterparty; don't retry.
COMPLIANCE_TEMPORARY_HOLD, COMPLIANCE_UNDER_REVIEWCompliance messages such as Transaction temporarily rejected…Retry once the hold expires or the review ends. The KYT state endpoint tells you the current state.

Blockchain or Avenia-balance input​

failureCodefailureReason todayWhat to do
INSUFFICIENT_BALANCEinsufficient balance to complete this transactionTop up the balance, then request a new quote. Check GET /v2/account/balances before quoting.
INVALID_SIGNATURE, INSUFFICIENT_ALLOWANCEinvalid permit signature, invalid personal signature, invalid signature, not enough allowanceRe-sign the transaction or raise the allowance, then request a new quote.
TRANSACTION_DEADLINE_EXPIREDthe transaction deadline expired…Request a new quote and try again.

Delivery​

failureCodeReason inside ticket failed partially: … todayWhat to do
LIMIT_EXCEEDEDuser doesn't have enough limit availableThe output limit was exceeded. The amount is in your balance; send it again once the limit allows. Check your limits with Get Account Limits.
RECEIVER_PIX_KEY_INVALID, RECEIVER_BR_CODE_INVALID, RECEIVER_ACCOUNT_INVALIDinvalid pix key, invalid br code, invalid pix input, double check your bank account informationFix the beneficiary data.
RECEIVER_ACCOUNT_BLOCKED_BY_BANK, RECEIVER_ACCOUNT_CLOSED, RECEIVER_BANK_REJECTED, RECEIVER_BR_CODE_NOT_PAYABLEreceiver bank account is blocked, receiver bank account is closed, payment was rejected by the receiver, the qr code payment was rejected by the receiverThe receiving institution refused it. Confirm the account with the beneficiary.
RECEIVER_BANK_TIMEOUT, PAYOUT_UNAVAILABLEreceiver bank has timed out, DICT unavailableTemporary. Send again from your balance.
RECEIVER_BLOCKED_BANK_INSTITUTION, RECEIVER_BLOCKED_TAX_ID, RECEIVER_BLOCKED_WALLET_ADDRESSreceiver bank institution is blocked, receiver tax id is blocked, receiver wallet address is blockedThis beneficiary can't be paid. Use another one.
THIRD_PARTY_PAYOUTthird party pay-out rejectedThe beneficiary isn't the account holder and the account doesn't send third-party payouts.
PAYOUT_FAILED, PAYOUT_RETURNEDpayout failed, payout returned, payout abandoned, pix failedThe payment network didn't complete the payout. Check the beneficiary data; if it's right, contact support with the ticket id.

INTERNAL_ERROR with failureReason internal error means something failed on Avenia's side: contact support with the ticket id.

Expired tickets​

Every ticket has an expiration (expiresAt when you read it back). Treat it as the deadline you show your user.

  • Nothing changes automatically at expiration. The ticket stays UNPAID and no webhook is sent. Cancel it with PATCH /v2/account/tickets/{id}/cancel to close it on your side.
  • A PIX paid after expiration, or after you canceled the ticket, doesn't pay the ticket. It is returned to the payer; if it hasn't come back, contact support with the PIX end-to-end ID.
  • COP, ARS and MXN: the payment link, key or account in the ticket has its own window on the local payment network. A payment the network accepts inside that window is credited to the ticket, even if expiration has already passed; after the window the network refuses it. Don't reuse old deposit instructions — create a new ticket.
  • The default expiration depends on the operation; the ticket response always carries the exact value. Some quotes accept customDuration to set it — see Available Combinations.