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
| Status | Final? | Meaning |
|---|---|---|
UNPAID | No | Created, waiting for the input. Stays UNPAID after expiration — see Expired tickets. |
PROCESSING | No | The input was received and the operation is running. |
ON-HOLD | No | Paused for compliance review during the deposit, before it is settled. |
PAID | Yes | Delivered. For BRL PIX payouts, settled at the beneficiary's institution. |
FAILED | Yes | The operation didn't complete. See the table below for where the funds are. |
PARTIAL-FAILED | Yes | One phase completed and a later one failed. The funds are in your Avenia balance — see the table below. |
CANCELED | Yes | You 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 failed | Status | Webhook | The funds |
|---|---|---|---|
| A BRL PIX deposit was rejected (limits, compliance, verification) | FAILED | DEPOSIT-FAILED | Refunded 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 sender | PARTIAL-FAILED | DEPOSIT-SUCCESS, DELIVERY-PROCESSING, then DELIVERY-PARTIAL-FAILED | Credited 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) | FAILED | DEPOSIT-FAILED | Nothing was debited. |
| The payout was refused or failed after the input was debited or converted | PARTIAL-FAILED | DELIVERY-PARTIAL-FAILED | Credited 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 error | FAILED | DEPOSIT-FAILED or DELIVERY-FAILED | failureCode 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
failureCode | failureReason today | What to do |
|---|---|---|
LIMIT_EXCEEDED | user does not have enough limit | The 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_DEPOSIT | third party deposit is not allowed for this user | The payer isn't the account holder and the account doesn't accept third-party deposits. Pay from the holder's own bank account. |
INTERNAL_ERROR | deposit could not be verified, funds returned | The 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_ID | sender bank institution is blocked, sender tax id is blocked | The sender can't pay this account. Use another sender. |
USER_BLOCKED | user is blocked, funds returned. Contact compliance@avenia.io | Contact compliance. |
COMPLIANCE_REJECTED / COMPLIANCE_UNDER_REVIEW | kyb verification rejected / kyb verification pending, kyb verification not completed in time | The account's compliance review did not clear. Contact compliance@avenia.io. |
FEE_ACCOUNT_INSUFFICIENT_BALANCE | insufficient balance on the fee account, please top it up | Your fee account can't cover the fees. Top it up and create a new ticket. |
COMPLIANCE_REJECTED | Compliance messages such as Transaction rejected… | Permanent for this counterparty; don't retry. |
COMPLIANCE_TEMPORARY_HOLD, COMPLIANCE_UNDER_REVIEW | Compliance 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
failureCode | failureReason today | What to do |
|---|---|---|
INSUFFICIENT_BALANCE | insufficient balance to complete this transaction | Top up the balance, then request a new quote. Check GET /v2/account/balances before quoting. |
INVALID_SIGNATURE, INSUFFICIENT_ALLOWANCE | invalid permit signature, invalid personal signature, invalid signature, not enough allowance | Re-sign the transaction or raise the allowance, then request a new quote. |
TRANSACTION_DEADLINE_EXPIRED | the transaction deadline expired… | Request a new quote and try again. |
Delivery
failureCode | Reason inside ticket failed partially: … today | What to do |
|---|---|---|
LIMIT_EXCEEDED | user doesn't have enough limit available | The 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_INVALID | invalid pix key, invalid br code, invalid pix input, double check your bank account information | Fix the beneficiary data. |
RECEIVER_ACCOUNT_BLOCKED_BY_BANK, RECEIVER_ACCOUNT_CLOSED, RECEIVER_BANK_REJECTED, RECEIVER_BR_CODE_NOT_PAYABLE | receiver bank account is blocked, receiver bank account is closed, payment was rejected by the receiver, the qr code payment was rejected by the receiver | The receiving institution refused it. Confirm the account with the beneficiary. |
RECEIVER_BANK_TIMEOUT, PAYOUT_UNAVAILABLE | receiver bank has timed out, DICT unavailable | Temporary. Send again from your balance. |
RECEIVER_BLOCKED_BANK_INSTITUTION, RECEIVER_BLOCKED_TAX_ID, RECEIVER_BLOCKED_WALLET_ADDRESS | receiver bank institution is blocked, receiver tax id is blocked, receiver wallet address is blocked | This beneficiary can't be paid. Use another one. |
THIRD_PARTY_PAYOUT | third party pay-out rejected | The beneficiary isn't the account holder and the account doesn't send third-party payouts. |
PAYOUT_FAILED, PAYOUT_RETURNED | payout failed, payout returned, payout abandoned, pix failed | The 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
UNPAIDand no webhook is sent. Cancel it withPATCH /v2/account/tickets/{id}/cancelto 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
expirationhas 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
customDurationto set it — see Available Combinations.