Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Settlement and Balance

A captured payment is not paid to you at once. A settlement pays a group of captured payments, in the output currency of each sale's quote, after Avenia takes the MDR and any reserve. This page covers what a sale costs (its quote and receivables), paying a sale to a wallet, reading a settlement, and your balance. What you will receive and when is on Schedule, Statement and Timeline.

Quote and receivables​

Every payment answer carries the sale's quote and its receivables, at the top level of the payment. They are on the answer to POST /payments, on GET /payments/{payment-id}, on the answer to a saved-card charge and on the ACQUIRING-PAYMENT-CAPTURED event. When they could not be read at that moment, quote is left out and receivables is empty, and GET /payments/{payment-id} returns them.

JSON
"quote": {
"outputCurrency": "USDC",
"outputPaymentMethod": "POLYGON",
"outputAmount": "26.504629",
"rate": "5.4",
"pairName": "USDCBRL",
"inputFee": "4.875",
"conversionFee": "1.5",
"markupFee": "0",
"outFee": "0.4",
"gasFee": "0.1",
"expiresAt": "2026-10-08T15:05:00Z"
},
"receivables": [
{ "installmentNumber": 1, "expectedDate": "2026-11-09", "amount": "137.62", "expectedAmount": "25.133967" }
]
FieldMeaning
quoteThe quote the sale was opened from, as on its checkout session: outputCurrency, outputPaymentMethod, outputAmount, rate, pairName, its fees in BRL (inputFee, conversionFee, markupFee, outFee, gasFee) and expiresAt. It is the whole price of the sale: the quote fixes the rate and every fee when it is created, and the capture changes none of them.
receivablesWhat the acquirer is expected to pay, installment by installment: installmentNumber, expectedDate, amount (in BRL, net of the MDR, the main account's markup and the reserve, before the price of an early settlement) and expectedAmount (in the quote's outputCurrency: the installment's share of the quote). expectedDate is a date (YYYY-MM-DD) in an answer and an RFC 3339 instant in an event; before the schedule is written it is "" in an answer and absent in an event.

Each part of the price of a sale is a field of its quote:

WhatWhere it is
The currency you are paid inquote.outputCurrency: BRLA, USDC or USDT. quote.outputPaymentMethod is where: INTERNAL, or the chain of the wallet the sale is paid to.
The MDRquote.inputFee, in BRL: your account's card price (a percentage of the amount plus a fixed fee) on the sale's amount. It is the price when the sale was opened: a later change of your pricing does not reach a sale already made.
The conversion ratequote.rate: BRL per 1 unit of outputCurrency, read as pairName says. It is fixed when the quote is created; the payment's capture does not change it.
What Avenia charges to convert and deliverquote.conversionFee, quote.outFee and quote.gasFee, in BRL.
The main account's markupquote.markupFee, in BRL, set with the quote's markup fields (see card sale quotes); "0" when the quote has no markup.
When the payment was capturedcapturedAt of the payment.

The sale delivers its quote. Each part of a sale that is paid (the part settled early, each installment, the reserve) converts as its share of the quote, so together they deliver the quote's outputAmount and charge its fees exactly. A refund or the price of an early settlement lowers what converts, and the sale then delivers that share. The sandbox account uses example pricing, not your commercial terms: the quote of each payment shows what applies to it.

How the main account is paid its markup​

The main account's markups (on the sale, on the conversion and on a sub-account's early settlement) are accrued to the main account as its sub-accounts' sales are paid. They are paid in a settlement of kind MAIN_MARKUP, on every settlement pass: it pays the main account's whole markup balance that is free at that moment (what the main account owes, and what other open settlements have not claimed, is left out). The payout is always in BRLA, whatever the output currency of the sales' quotes. The conversion markup is paid in BRLA like the rest. A settlement pass that finds no free markup creates no MAIN_MARKUP settlement. The main account can also bring its markup that still waits for the acquirer forward with an early settlement of beneficiary MAIN. The main account reads what is waiting in markupDeferredAmount, markupPayableAmount and fxMarkupPayableAmount of the balance.

Settling a sale to a wallet​

A sale is paid where the output of its quote goes. A quote whose output is INTERNAL is paid to your account's balance, and the sale names no wallet. A quote whose output is on a blockchain is paid to the wallet you name with beneficiaryWalletId on that sale (POST /checkout-sessions or POST /payments), exactly as a ticket's beneficiaryWalletId for a blockchain output: the id of one of your beneficiary wallets, your own or a liquidity provider's.

JSON
"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c"
  • The wallet must be a beneficiary wallet of the account that sells (the sub-account in subAccountId, when you sell for one), on the chain of the quote's output. There is nothing else to register: any of your beneficiary wallets on that chain can be named.
  • Each payment carries its own wallet. Two payments of the same account can be paid to two different wallets.
  • Refusals, all with 400 InvalidFieldError: beneficiaryWalletId is invalid, as a ticket is refused: an id that is not a UUID, that is unknown, or that is another account's wallet; a wallet whose chain is not the chain of the quote's output; no beneficiaryWalletId when the quote's output is on a blockchain; and a wallet whose address is the wallet of another account of your workspace that is hidden from your dashboard ("extraInfo": "the destination sub-account is hidden").
  • What it does. A sale paid to a wallet is settled like any other sale, to that wallet on its chain, in the quote's output currency. Money brought forward from it by an early settlement you execute is paid to its wallet. It covers debts your account owes, as any sale does (receivableOffsetAmount). The rolling reserve held from it, when released, is paid to its wallet, as is what a won dispute returns.
  • It is fixed once the sale is made. A repeat of the quoteToken with another beneficiaryWalletId is a different request, refused with 409. The sale keeps the address and chain the wallet had when it was created: deleting the beneficiary wallet afterwards changes nothing for it.
  • Where you read it back. beneficiaryWalletId, with the wallet's walletAddress and walletChain, all "" when the sale is paid to your account's balance. They are on the checkout session, GET /payments/{payment-id}, every payment event, the answer to POST /payments and the answer to a saved-card charge, a repeat included. The settlement that pays the sale (GET /settlements/{settlement-id} and the settlement events) carries beneficiaryWalletId, and the wallet's address and chain in walletAddress and walletChain from the moment it is created.
  • A saved-card charge without the cardholder takes beneficiaryWalletId the same way.

Settlements​

When a settlement pays you, you receive ACQUIRING-SETTLEMENT-PAID (payload). If it did not go out, ACQUIRING-SETTLEMENT-HELD; the event never says why. A settlement that ends FAILED sends no event: you learn of it by reading the settlement, whose failureCode says why (see settlement failure codes).

Paid out in USDC or USDT: each payment is converted at its quote's rate, whatever day it is paid, and Avenia's fees (the quote's conversionFee, outFee and gasFee) and the main account's markup (markupFee) are its share of the quote's. The rolling reserve converts at that same rate when it is released. payoutAmount is the sum of what each payment buys, cut to 6 decimals. The fxRate of a settlement read is derived from the whole settlement: the reais it delivers over the units they bought (BRL per 1 unit of payoutCurrency).

Read a settlement, payment by payment​

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/settlements/{settlement-id}?limit=&cursor=

The id comes from the settlement events. A settlement of another account or sub-account answers 404.

JSON
{
"id": "c2d8a0f4-7b13-4e69-95a2-1f6e8d0b3c47",
"settlementType": "SALES",
"status": "PAID",
"failureCode": "",
"paymentMethod": "CREDIT",
"windowStart": "2026-10-08T00:00:00Z",
"windowEnd": "2026-10-09T00:00:00Z",
"grossAmount": "100",
"mdrVariable": "2.99",
"mdrFixed": "0.39",
"earlySettlementFee": "0",
"earlySettlementMainMarkup": "0",
"fxSpread": "0",
"reserveAmount": "5",
"receivableOffsetAmount": "0",
"deferredAmount": "37.47",
"netAmount": "54.15",
"mainMarkup": "0",
"payoutCurrency": "BRLA",
"payoutAmount": "54.15",
"fxRate": null,
"walletChain": "POLYGON",
"walletAddress": "0x9f3a6c0d1b7e4a58c2d96e0f1a3b5c7d8e9f0a12",
"beneficiaryWalletId": "",
"txHash": "sandbox-0f3a...",
"paidAt": "2026-10-09T18:30:41Z",
"createdAt": "2026-10-09T18:30:12Z",
"items": [
{
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"externalId": "order-10045",
"grossAmount": "100",
"capturedBasis": "100",
"refundedBasis": "0",
"rollingReservePct": "0.05",
"mainMarkup": "0",
"mdrVariable": "2.99",
"mdrFixed": "0.39",
"reserveAmount": "5",
"fxSpread": "0",
"deferredAmount": "37.47",
"netAmount": "54.15"
}
],
"cursor": ""
}
  • settlementType is SALES, DEFERRED_RELEASE, RESERVE_RELEASE, EARLY_SETTLEMENT or MAIN_MARKUP; status is DRAFT, APPROVED, EXECUTING, PAID, FAILED or HELD, and failureCode is "" unless it is FAILED (see settlement failure codes); paymentMethod is CREDIT or DEBIT.
  • externalId is your own order id, to match each item against your records. grossAmount is what was captured and not refunded before settling; every component is the amount charged on that payment, and netAmount is gross minus all of them. rollingReservePct is the reserve percentage applied. Each item names its payment in paymentId, and the rest of the payment's price (the MDR, the rate, the main account's markup) is that payment's quote: read it with GET /payments/{payment-id}. receivableOffsetAmount is the part of what you owe that this settlement netted off (only a DEFERRED_RELEASE nets a debt off); deferredAmount is the part that waits for the acquirer.
  • Items come in pages of limit (default 100, at most 500). When there are more, cursor is set: send it back as cursor for the next page. Empty means the last page.
  • earlySettlementFee and earlySettlementMainMarkup are set on an EARLY_SETTLEMENT settlement: what the early settlement it pays cost, Avenia's fee and the main account's markup. They are "0" on every other kind.
  • Only a SALES settlement has items. A DEFERRED_RELEASE or RESERVE_RELEASE pays amounts kept back from earlier sales, an EARLY_SETTLEMENT pays an early settlement and a MAIN_MARKUP pays the main account its markup, in BRLA; the event of each lists what it released.

Settling in the sandbox​

In the sandbox settlement runs on request, not on a schedule, so your refund tests are not affected by it: you settle when you choose. Everything is real except the transfer: the fees, the reserve, the ledger and the events are computed as in production, and the payout is simulated (no tokens are sent; txHash starts with sandbox-).

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/settlements/settle-now

The body is {}. It settles your captured payments now, the same pass production runs on its schedule, and answers 200:

JSON
{ "settlements": [ { "settlementId": "c2d8a0f4-7b13-4e69-95a2-1f6e8d0b3c47", "paymentMethod": "CREDIT", "items": 3, "netAmount": "162.45", "held": false } ], "skipped": {} }
  • held: false: the payout goes out within seconds and ACQUIRING-SETTLEMENT-PAID follows within about a minute. held: true: it was kept back and ACQUIRING-SETTLEMENT-HELD follows.
  • No settlements: there was nothing to settle. skipped then counts, by reason, the captured payments left out (for example a refund still in flight).
  • Asking twice at once runs one pass, not two.
  • Outside the sandbox this route answers 404 settling on demand exists only in the sandbox; here settlements run on their own schedule.

Balance​

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/balance

What you have with Avenia, all in BRL:

JSON
{
"currency": "BRL",
"payableAmount": "54.15",
"deferredPayableAmount": "37.47",
"reserveAmount": "5",
"receivablesOutstandingAmount": "0",
"capturedUnsettledAmount": "150",
"main": {
"bufferAmount": "2000",
"bufferTargetAmount": "2500",
"markupDeferredAmount": "0",
"markupPayableAmount": "0",
"fxMarkupPayableAmount": "0",
"receivableAmount": "0"
}
}
FieldMeaning
currencyAlways BRL.
payableAmountWhat you are owed now.
deferredPayableAmountWhat you are owed once the acquirer pays the installments: it waits deferred until then.
reserveAmountWhat is held as your rolling reserve.
receivablesOutstandingAmountThe debt you still owe, for example a refund above your cover, a chargeback, or an FX difference.
capturedUnsettledAmountCaptured payments that are in no settlement yet, before any fee, reserve or early settlement.
mainOnly for the main account, never for a sub-account: bufferAmount is the workspace's buffer and bufferTargetAmount its target; markupDeferredAmount and markupPayableAmount are the main's markup on its sub-accounts' payments (held until the acquirer pays the installment, then due) and fxMarkupPayableAmount its markup on their conversions; receivableAmount is what the main owes of a markup given back.