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 failureReason 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 failureReason 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	failureReason 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.

failureReason reference

Most failed deliveries have the form ticket failed partially: <reason> - tokens returned to user's wallet, where "wallet" means your Avenia balance. A compliance rejection that couldn't be returned to the sender ends PARTIAL-FAILED with its own message instead: a compliance text, a kyb verification … reason, deposit could not be verified, funds returned, or a fee-account reason. In that case the funds are in your balance, not returned to the sender. The reasons below are what you can act on.

Deposit

failureReason	What to do
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 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.
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 bank institution is blocked, sender tax id is blocked, sender is blocked	The sender can't pay this account. Use another sender.
user is blocked, funds returned. Contact compliance@avenia.io	Contact compliance.
kyb verification pending, kyb verification rejected, kyb verification not completed in time	Complete the company's KYB for this rail, then create a new ticket.
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 messages such as Transaction rejected…	The text says whether retrying the same counterparty can succeed.

Blockchain or Avenia-balance input

failureReason	What to do
insufficient balance to complete this transaction	Top up the balance, then request a new quote. Check GET /v2/account/balances before quoting.
invalid permit signature, invalid personal signature, invalid signature, not enough allowance	Re-sign the transaction or raise the allowance, then request a new quote.
the price moved beyond the accepted slippage…, the transaction deadline expired…	Request a new quote and try again.

Delivery

Reason inside ticket failed partially: …	What to do
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.
invalid pix key, invalid br code, invalid pix input, double check your bank account information	Fix the beneficiary data.
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.
DICT unavailable, receiver bank has timed out	Temporary. Send again from your balance.
receiver bank institution is blocked, receiver tax id is blocked, receiver is blocked, receiver wallet address is blocked	This beneficiary can't be paid. Use another one.
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 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 on its own 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.