Skip to main content

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-account endpoints below, always with your main account's credentials.
Availability

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​

  1. Fund it. Deposit to the Fee Account by Pix or by sending stablecoins (see Deposit).
  2. Quote and create the ticket with feeSettlement=FEE_ACCOUNT. The quote does not check the Fee Account's balance, like any other quote.
  3. 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.
  4. 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" and failureCode: "FEE_ACCOUNT_INSUFFICIENT_BALANCE" (failureReason reads insufficient balance on the fee account, please top it up). Nothing is charged; an INTERNAL input stays in your account and a Pix deposit is returned. See Ticket failed for Fee Account balance.
  5. 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.
  6. 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 currencyFee Account balance used
BRL, BRLABRLA
USD, USDC, USDTUSDC or USDT
EUR, EURCEURC

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​

GET/v2/account/fee-account

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account" \
-H "Authorization: Bearer <token>"

Response​

JSON
{
"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​

StatusWhen
404Your account has no Fee Account.
400A 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​

GET/v2/account/fee-account/deposit

Parameters​

Optional​

FieldTypeDescription
amountstringFixed amount, in BRL, for the Pix code. Leave it empty to let the payer choose the amount.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account/deposit?amount=150" \
-H "Authorization: Bearer <token>"

Response​

JSON
{
"brCode": "00020126580014br.gov.bcb.pix0136XXXX...6304A708",
"wallets": [
{ "chain": "EVM", "walletAddress": "0x5aF3e1C0b5b3E2a1f0C9d8e7B6a5F4e3D2c1XXXX" },
{ "chain": "TRON", "walletAddress": "TQ5NzH1p9gYb8pXc7K3vJdQ2rW4eT6XXXX" }
]
}
  • brCode is a static Pix code (copy and paste, or render it as a QR code). Pix deposits are credited as BRLA.
  • wallets are 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​

GET/v2/account/fee-account/statement

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:

FieldTypeDescription
ticketIdstringThe ticket the fee was for. On a fee credited back, the ticket that was refunded.
subAccountIdstringThe sub-account that created that ticket. Absent when the main account created it.

Deposits and withdrawals have neither field.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/fee-account/statement" \
-H "Authorization: Bearer <token>"

Response​

JSON
{
"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
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​

StatusWhen
400FEE_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:

JSON
{
"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.

Keep it funded

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":

JSON
{
"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"
}
}
}