Fee Account
The Fee Account is a dedicated account that pays the Avenia fees of your tickets. Instead of deducting the fees from each ticket's amount, you keep a balance in the Fee Account and the fees are charged to it. The ticket's full amount reaches its destination.
It belongs to your main account and has one purpose:
- It only receives deposits (Pix or stablecoins) and pays fees. You cannot quote, create tickets, convert, withdraw, send or register beneficiaries from it.
- You manage it through the
/v2/account/fee-accountendpoints below, always with your main account's credentials.
The Fee Account is enabled by Avenia per account. If you would like to use it, contact your Avenia account manager. Until it is enabled, GET /v2/account/fee-account returns 404.
How it works
- Fund it. Deposit to the Fee Account by Pix or by sending stablecoins (see Deposit).
- Quote and create the ticket with
feeSettlement=FEE_ACCOUNT. The quote does not check the Fee Account's balance, like any other quote. - When the ticket starts processing, its fees are set aside on the Fee Account balance. Fees set aside for one ticket can't be used by another, so tickets running at the same time never count on the same balance.
- If the balance doesn't cover the fees, the ticket fails like any ticket without balance: you receive the usual ticket webhooks with
status: "FAILED"andfailureCode: "FEE_ACCOUNT_INSUFFICIENT_BALANCE"(failureReasonreadsinsufficient balance on the fee account, please top it up). Nothing is charged; anINTERNALinput stays in your account and a Pix deposit is returned. See Ticket failed for Fee Account balance. - When the ticket is paid, the fees set aside are charged right away, in the token that matches the ticket's input currency (see Which balance pays). If that charge fails for a technical reason, the fees are added to your end-of-month invoice instead.
- Refunds: a refund ticket is never refused for Fee Account balance. When a ticket paid through the Fee Account is refunded, the output fee it charged is credited back to the Fee Account.
Which balance pays
The fee is charged in the token of the ticket's input currency. Keep a balance in the token(s) you operate with:
| Ticket input currency | Fee Account balance used |
|---|---|
BRL, BRLA | BRLA |
USD, USDC, USDT | USDC or USDT |
EUR, EURC | EURC |
Tickets whose input currency is not in this table cannot be quoted with feeSettlement=FEE_ACCOUNT.
Get the Fee Account
Returns the Fee Account and its balances.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account" \
-H "Authorization: Bearer <token>"
Response
{
"id": "7c70ffc4-XXXX-XXXX-XXXX-cf67b5de525b",
"mainAccountId": "553106d0-XXXX-XXXX-XXXX-c30ae13c192a",
"createdAt": "2026-10-08T14:37:02Z",
"balances": {
"BRLA": "1250.4",
"EURC": "0",
"USDC": "310",
"USDM": "0",
"USDT": "0"
}
}
balances has the same format as GET /v2/account/balances.
Errors
| Status | When |
|---|---|
404 | Your account has no Fee Account. |
400 | A subAccountId parameter was sent. The Fee Account belongs to the main account, so these endpoints don't take one. |
Deposit
Returns how to deposit to the Fee Account: a static Pix code and the stablecoin wallets.
Endpoint
Parameters
Optional
| Field | Type | Description |
|---|---|---|
amount | string | Fixed amount, in BRL, for the Pix code. Leave it empty to let the payer choose the amount. |
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account/deposit?amount=150" \
-H "Authorization: Bearer <token>"
Response
{
"brCode": "00020126580014br.gov.bcb.pix0136XXXX...6304A708",
"wallets": [
{ "chain": "EVM", "walletAddress": "0x5aF3e1C0b5b3E2a1f0C9d8e7B6a5F4e3D2c1XXXX" },
{ "chain": "TRON", "walletAddress": "TQ5NzH1p9gYb8pXc7K3vJdQ2rW4eT6XXXX" }
]
}
brCodeis a static Pix code (copy and paste, or render it as a QR code). Pix deposits are credited asBRLA.walletsare the Fee Account's addresses for stablecoin deposits. Send each token on its matching network.
Statement
Lists the Fee Account's balance changes: deposits, fees charged and fees credited back.
Endpoint
It takes the same parameters (cursor, createdAfter, createdBefore) and returns the same format as the Account Statement, with two more fields on each fee charged or credited back:
| Field | Type | Description |
|---|---|---|
ticketId | string | The ticket the fee was for. On a fee credited back, the ticket that was refunded. |
subAccountId | string | The sub-account that created that ticket. Absent when the main account created it. |
Deposits and withdrawals have neither field.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account/statement" \
-H "Authorization: Bearer <token>"
Response
{
"logs": [
{
"id": "7c1e2f30-5a4b-4c8d-9e0f-1a2b3c4d5e6f",
"token": "BRLA",
"balanceChange": "-4.6",
"finalBalance": "1250.4",
"description": "[DEBIT] Fee account charge of ticket 3f1c9a20-7d4e-4b8a-9c1f-2e5d6a7b8c90",
"createdAt": "2026-10-09T14:20:00.120391Z",
"ticketId": "3f1c9a20-7d4e-4b8a-9c1f-2e5d6a7b8c90",
"subAccountId": "5e2b7c41-8a90-4d3f-b6e1-0c9d8a7f6e52"
},
{
"id": "0b9a8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d",
"token": "BRLA",
"balanceChange": "1000",
"finalBalance": "1255",
"description": "[CREDIT] Process ticket output: BRLA delivery",
"createdAt": "2026-10-08T09:05:00.402117Z"
}
],
"cursor": "MjgzLTE3NDM1MTU4MjA4MDY="
}
Paying a ticket's fees with the Fee Account
Send feeSettlement=FEE_ACCOUNT in the quote, from your main account or any sub-account:
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=1000&outputCurrency=BRLA&outputPaymentMethod=INTERNAL&inputThirdParty=false&outputThirdParty=false&blockchainSendMethod=PERMIT&feeSettlement=FEE_ACCOUNT" \
-H "Authorization: Bearer <token>"
The quote response shows "feeSettlement": "FEE_ACCOUNT", and its appliedFees are not deducted from the ticket's amount. Create the ticket with the quote token as usual.
To use the Fee Account without sending feeSettlement on every quote, set it as your account's default mode: see Fee Settlement.
Errors
| Status | When |
|---|---|
400 | FEE_ACCOUNT is not enabled for your account, or the input currency is not supported (see Which balance pays). |
The quote is not refused when the Fee Account's balance is low; that is decided when the ticket is processed.
Ticket failed for Fee Account balance
When the Fee Account doesn't cover a ticket's fees, the ticket usually ends FAILED with the usual ticket webhooks (DEPOSIT-FAILED, then TICKET-COMPLETE) and the deposit is returned. If the deposit can't be returned to the sender, the ticket ends PARTIAL-FAILED instead and the amount is credited to your balance — see Ticket Lifecycle and Failures. Identify the case by failureCode FEE_ACCOUNT_INSUFFICIENT_BALANCE together with quote.feeSettlement:
{
"type": "DEPOSIT-FAILED",
"ticket": {
"id": "462f94ac-XXXX-XXXX-XXXX-933b67f4768f",
"status": "FAILED",
"failureReason": "insufficient balance on the fee account, please top it up",
"failureCode": "FEE_ACCOUNT_INSUFFICIENT_BALANCE",
"quote": {
"inputCurrency": "BRLA",
"inputPaymentMethod": "INTERNAL",
"inputAmount": "10",
"outputCurrency": "USDC",
"outputPaymentMethod": "INTERNAL",
"feeSettlement": "FEE_ACCOUNT",
"appliedFees": [
{ "type": "Conversion Fee", "amount": "0.11", "currency": "BRLA" }
]
}
}
}
Deposit to the Fee Account and create a new ticket.
A nearly empty Fee Account can refuse a ticket right after another ticket's fees were charged, while that charge is still being confirmed. Keep a margin above your expected fees.
Fee Account in webhooks
Webhooks about the Fee Account itself, such as a deposit to it, carry the Fee Account's id (the one returned by GET /v2/account/fee-account) in ticket.userId. A deposit to the Fee Account has reason: "Fee account top-up":
{
"type": "TICKET-COMPLETE",
"ticket": {
"userId": "7c70ffc4-XXXX-XXXX-XXXX-cf67b5de525b",
"status": "PAID",
"reason": "Fee account top-up",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10",
"outputCurrency": "BRLA",
"outputAmount": "10"
}
}
}