Quote and Ticket FAQ
Short answers to the questions integrators ask most about tickets, quotes, fees, limits and retries. Each answer links to the page with the full detail.
Which ticket status means the beneficiary's bank credited the PIX?
PAID. For a BRL PIX payout, PAID means the PIX was confirmed as settled at the beneficiary's institution, so nothing else is pending. A PIX that was refused ends PARTIAL-FAILED, and a ticket that failed before the payout ends FAILED.
See PIX payout outcomes.
Where do the funds go when a ticket ends PARTIAL-FAILED?
To your Avenia balance. They are not sent back on-chain. They stay in the currency the operation had reached: BRLA when a PIX payout is refused, USDC when a BRL → USD payout fails after the conversion. A deposit rejected by compliance that can't be returned to the sender is credited as a token too; the table says which one. From your balance you can pay them out again with a new quote.
See Where the money is when a ticket fails.
What does ticket failed partially: … - tokens returned to user's wallet mean?
The payout failed after the input was already debited or converted, and "wallet" means your Avenia balance: the amount is there. The part in the middle is the reason, for example invalid pix key or receiver bank account is closed. The reference table says what to do for each one.
Why was a PIX deposit rejected, and where is the money?
When a deposit fails the compliance or limit checks, the ticket ends FAILED, you get a DEPOSIT-FAILED webhook, and the full amount is refunded to the payer's account. failureReason says why. reason reads Refund in progress. at first and later includes the refund end-to-end ID.
See Deposit validation before credit and the deposit failure reasons.
The deposit failed with sender tax id is blocked. What can the payer do?
This sender can't pay this account, and the deposit was returned. The same goes for sender bank institution is blocked (a bank blocked for pay-ins) and sender is blocked. The payment has to come from another sender.
See the deposit failure reasons.
Which limits apply, and what happens when an operation goes over them?
Each account (the main account and each sub-account separately) has monthly limits per currency and direction, plus a global limit in USD that covers all currencies. A ticket that doesn't fit is refused at creation with 400 user does not have enough BRL limit for operation (or …GLOBAL limit…). If the limit runs out when the ticket runs, a PIX deposit is refunded to the payer, and a payout ends PARTIAL-FAILED with the amount kept in your balance.
See Limits.
The customer paid an expired QR code, and the ticket is still UNPAID. Where is the money?
A PIX paid after the ticket's expiration, or after you canceled it, doesn't pay the ticket and is returned to the payer. The ticket stays UNPAID; cancel it to close it, and if the money hasn't come back to the payer, contact support with the PIX end-to-end ID.
See Expired tickets.
Why does the quote return InputAmount is invalid?
The amount isn't a valid number. Use a dot as the decimal separator (10.5, not 10,5), with up to 2 decimal places for fiat currencies and 6 for tokens. Send exactly one of inputAmount and outputAmount, never both.
See Common field errors and Crypto to PIX.
How long is a quote valid?
The quoteToken is valid for 15 seconds, so create the ticket right after the quote. The ticket then has its own expiration (expiresAt when you read it back). It depends on the operation, and the ticket response always has the exact value.
See The quote token is the once-only key and Expired tickets.
Why does creating the ticket return quoteToken is invalid?
Either the quote expired, or the quote and the ticket name different accounts. When you act for a sub-account, send the same subAccountId on both. On the ticket it goes in the query string (POST /v2/account/tickets/?subAccountId=...). Sending it only on the quote, or only on the ticket, returns this same error.
Why does my statement show BRLA and not BRL?
Your Avenia balance is held in tokens, and BRLA is Avenia's Brazilian real token: 1 BRLA = 1 BRL. A PIX deposit of R$100 becomes 100 BRLA, minus any fees deducted under your fee settlement mode. When you pay out by PIX, the BRLA is converted back to BRL 1:1.
How do I match a PIX to the BRLA credit in my balance?
Go through the ticket. A PIX deposit's ticket carries brazilianFiatSenderInfo.endToEndId, a PIX payout's carries brazilianFiatReceiverInfo.endToEndId, and GET /v2/account/tickets/ filters by endToEndId and externalId. A PIX sent to your static key or BR Code without a ticket gets a ticket automatically.
See Matching a payment to a ticket.
Can the fees be charged to the main account instead of the sub-account?
With the FEE_ACCOUNT fee settlement mode, Avenia's fees are charged to your fee account, which belongs to the main account and pays for the operations of the main account and every sub-account. With EOM they are billed at the end of the month, and with IMMEDIATE they are deducted from each operation. Avenia enables EOM and FEE_ACCOUNT per account.
See Fees in a quote and Fee Account.
The ticket is PAID, but my balance hasn't changed yet. Is something wrong?
No. A balance can lag a just-completed operation by a few seconds. The ticket status, or its webhook, is the source of truth for whether an operation finished.
Where do I get statements and reports?
GET /v2/account/statement lists every balance change. To export a period as files, use the async reports: POST /v2/account/reports/statements for balance changes and POST /v2/account/reports/transactions for ticket history. Add subAccountId for a sub-account.
See Account Statement and Async Reports.
Is POST /v2/account/tickets/ idempotent on externalId?
No. externalId is your own free-text reference, and Avenia doesn't enforce uniqueness: two tickets with the same externalId are two tickets. The only key the API enforces is the quote token, and one token creates at most one ticket.
See externalId is your reference, not a key.
The response to POST /tickets was lost. If I post again, will the payout happen twice?
It can, if you quote again and create a new ticket without checking first. Wait until your own request has fully timed out, then look the ticket up with GET /v2/account/tickets/?externalId=.... If a ticket comes back, follow it. If the list is empty, quote again and create the ticket with the same externalId.
Will I get a 409 if I create the same ticket twice?
No, creating a ticket never returns 409. Re-sending a quote token within its 15 seconds returns 400 cannot reuse quote token, which means the first request did create a ticket. After 15 seconds you get quoteToken is invalid, which tells you nothing about whether a ticket exists.
See The quote token is the once-only key.
I read a ticket right after creating it and got 404. Why?
A ticket that belongs to a sub-account returns 404 when you read it without subAccountId. Read it with the same subAccountId you used on the quote and the ticket: GET /v2/account/tickets/{ticketId}?subAccountId=....