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.

Early settlements

Credit card sales in installments are paid by the acquirer as each installment falls due. An early settlement pays you part of that money earlier, for a fee that counts the days between the day of the early settlement and the day the acquirer is expected to pay.

Nothing is settled early by itself: an early settlement happens only when you ask for a price on the money still waiting for the acquirer, and execute it. There are two kinds, named by beneficiary:

  • SUB: an account's delivery, settled early. The money from the account's own sales that still waits for the acquirer is paid to it now, in an EARLY_SETTLEMENT settlement. It is priced for the account that makes the call, or for the sub-account in subAccountId. On a sub-account's early settlement (subAccountId in the query, as on tickets), the main account can add its own markup, mainMonthlyPct.
  • MAIN: the main account's markup, settled early. The main account's markup on its sub-accounts' sales, which is otherwise paid to it as the acquirer pays (see how the main account is paid its markup), brought forward. Only the main account asks for it, on its own account; subAccountId in the body restricts it to one sub-account's sales.

An account cannot settle early while it has an open debt, while it is blocked, or beyond its early settlement limit. Early settlements are an admin action: a price needs a non-view-only access and executing needs an admin access.

Create an early settlement price​

An early settlement price says what an early settlement costs and moves no money. It is valid for 15 seconds. It is unrelated to the ticket quote (GET /quote/fixed-rate and its quoteToken).

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/early-settlements/prices

Parameters​

FieldTypeRequiredDescription
beneficiarystringYesSUB: your own sales, as the account that makes the call (or the sub-account in subAccountId, in the query). MAIN: the main account's markup on its sub-accounts' sales, for the main account only.
amountdecimalYesThe amount to bring forward in BRL, a JSON number or string with at most 2 decimal places, such as "1000.00", greater than 0. Asking for more than is available prices the smaller amount that is.
orderstringYesWhich installments to take first: FIRST takes the ones due soonest, LAST the farthest. An installment due on or before the day of the early settlement has nothing to bring forward.
paymentMethodstringWith SUBCREDIT or DEBIT.
subAccountIdstringNoWith MAIN only: price the markup on this one sub-account's sales, in the body. Without it, the price covers every sub-account's sales. A SUB price names its sub-account in the query, never in the body.
mainMonthlyPctdecimalNoWith SUB, on a sub-account's early settlement (subAccountId in the query): what the main account charges the sub-account for it, credited to the main account as a ticket's markup is. A rate per month as a decimal fraction ("0.015" is 1.5% a month), from 0 to 1, with at most 5 decimal places. Default 0. See the main account's markup.

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/acquiring/early-settlements/prices" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"beneficiary": "SUB",
"paymentMethod": "CREDIT",
"amount": "1000.00",
"order": "FIRST"
}'

Response​

JSON
{
"id": "5c0d7e2a-9b14-4a63-8f2e-1d3b5a7c9e04",
"beneficiary": "SUB",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"amount": "1000",
"order": "FIRST",
"earlySettlementDate": "2026-11-10",
"aveniaMonthlyPct": "0.025",
"mainMonthlyPct": "0",
"principalAmount": "1000",
"aveniaFee": "16.5",
"mainFee": "0",
"fundedAmount": "983.5",
"expiresAt": "2026-11-10T14:00:15Z",
"lines": [
{
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"installmentNumber": 2,
"expectedDate": "2026-12-09",
"principalAmount": "1000",
"days": 29,
"aveniaFee": "16.5",
"mainFee": "0",
"fundedAmount": "983.5"
}
]
}

Pricing a sub-account's early settlement as the main account, with a markup of 1.5% a month:

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/acquiring/early-settlements/prices?subAccountId=a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"beneficiary": "SUB",
"paymentMethod": "CREDIT",
"amount": "1000.00",
"order": "FIRST",
"mainMonthlyPct": "0.015"
}'

principalAmount is what is brought forward, the fees are what the early settlement costs (Avenia's, and the main account's on a sub-account's early settlement), and fundedAmount is what the early settlement brings you: the principal minus the fees. When you are paid in USDC or USDT, the FX spread and the main account's FX markup on the conversion are then deducted, so the amount that arrives is smaller than fundedAmount. earlySettlementDate and each line's expectedDate are calendar dates (YYYY-MM-DD), not RFC 3339 instants like the other times: the fee counts whole days between the two. The early settlement is priced at the rates in force when priced, not those of the sale.

The main account's markup on a sub-account's early settlement​

On a SUB early settlement of a sub-account (subAccountId in the query, as on tickets), mainMonthlyPct sets what it charges the sub-account for it, on top of Avenia's aveniaMonthlyPct. Both are rates per month written as decimal fractions.

  • The fee. On each line, mainFee is principalAmount × mainMonthlyPct × days / 30, cut to 6 decimal places; the price's mainFee is the sum of its lines. fundedAmount is principalAmount - aveniaFee - mainFee. The main account's fee is paid to it with its other markups (see how the main account is paid its markup).
  • How the answer shows it. The price echoes it as mainMonthlyPct, with mainFee on each line and in total. The executed early settlement, its reads and ACQUIRING-EARLY-SETTLEMENT-DECIDED carry the same mainMonthlyPct and mainFee. Without mainMonthlyPct, they read "0".
  • Only on a sub-account's sales. A mainMonthlyPct on a MAIN price, or on a SUB price of the main account's own sales, is refused with 400 InvalidFieldError: mainMonthlyPct is invalid: the main account does not mark up its own sales.
  • Executing it. A price is executed under the account it was asked for: execute a sub-account's price with the same subAccountId in the query. The money is paid to the sub-account.
  • The cap. Avenia sets, per workspace, the highest monthly markup the main account may charge on an early settlement. Above it, the price is refused with 400 the main account's markup on the early settlement is above what Avenia allows for this workspace. The cap is checked again when the price is executed.

Execute an early settlement​

Endpoint​

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

Parameters​

FieldTypeRequiredDescription
X-API-IdempotencyKeyheaderYesAny string unique to this early settlement. The same key returns the same early settlement (200); the same key for another price answers 409 the idempotency key already executed another price.
priceIdstringYesThe id of an unexpired price. A price is executed only by the account that asked for it, and only once.

Response​

201 (or 200 on a repeat with the same key):

JSON
{
"id": "0e9d8c7b-6a5f-4e3d-9c2b-1a0f9e8d7c6b",
"beneficiary": "SUB",
"principalAmount": "1000",
"aveniaFee": "16.5",
"mainFee": "0",
"fundedAmount": "983.5",
"settlementId": "c2d8a0f4-7b13-4e69-95a2-1f6e8d0b3c47",
"settlementHeld": false,
"paymentIds": ["e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d"]
}

The money leaves with the EARLY_SETTLEMENT settlement in settlementId (ACQUIRING-SETTLEMENT-PAID), unless it was held (settlementHeld: true). Each sale's money is paid where that sale is paid: to the wallet it names, or to your account's balance. ACQUIRING-EARLY-SETTLEMENT-DECIDED also announces it. The main account's markup that is not settled early is paid to it in BRLA by a MAIN_MARKUP settlement.

Errors​

HTTPerrorWhat to do
400an early settlement names its beneficiary, a positive amount and the order FIRST or LAST, and a sub's also its user and payment methodFix the price request.
400an early settlement needs an idempotency keySend X-API-IdempotencyKey.
400InvalidFieldError: mainMonthlyPct is invalidAbove 1, more than 5 decimal places, or sent on a MAIN price or a SUB price of the main account's own sales. See the main account's markup.
400the main account's markup on the early settlement is above what Avenia allows for this workspaceOn the price or on its execution: price again with a lower mainMonthlyPct.
404NotFoundError: early settlement price not foundWrong price id, or not yours.
409the price expired; ask for a new oneAsk for a new price and execute it within 15 seconds.
409the price was already executed or the idempotency key already executed another priceUse a new price, or a new key.
409the priced installments are no longer available; ask for a new priceAsk for a new price.
409nothing is left to settle early on these paymentsThere is no installment with money left to bring forward.
409the account has an open debt; early settlement is available again once it is settledSettle the debt first.
409the account is blocked and may not receive payoutsContact Avenia.
409the early settlement limit has no room for this amountLower the amount: see the limit.
409early settlement is not available for this account now, early settlement is switched offContact Avenia.

Read early settlements​

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

The list is the acting account's early settlements, newest first: beneficiary is SUB (the default) or MAIN (the main account's own early settlements). limit defaults to 50, at most 100. The answer is {"earlySettlements": [...], "cursor": "..."}: send a non-empty cursor back as cursor for older ones.

JSON
{
"id": "0e9d8c7b-6a5f-4e3d-9c2b-1a0f9e8d7c6b",
"beneficiary": "SUB",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"earlySettlementDate": "2026-11-10",
"aveniaMonthlyPct": "0.025",
"mainMonthlyPct": "0",
"principalAmount": "1000",
"aveniaFee": "16.5",
"mainFee": "0",
"fundedAmount": "983.5",
"settlementId": "c2d8a0f4-7b13-4e69-95a2-1f6e8d0b3c47",
"settlementStatus": "PAID",
"createdAt": "2026-11-10T14:00:05Z",
"lines": [
{
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"installmentNumber": 2,
"expectedDate": "2026-12-09",
"principalAmount": "1000",
"days": 29,
"aveniaFee": "16.5",
"mainFee": "0",
"fundedAmount": "983.5",
"status": "EARLY_SETTLED",
"repaidAt": ""
}
],
"settlementFailureCode": ""
}

A line's status is EARLY_SETTLED until the acquirer pays the installment, then REPAID (CANCELED marks a line that was undone). settlementStatus and settlementFailureCode are those of the settlement that pays it: the code is "" unless that settlement is FAILED (see settlement failure codes).

Early settlement limit​

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/early-settlements/limit
JSON
{
"user": { "used": "1000", "ceiling": "5000", "available": "4000" },
"workspace": { "used": "1000", "ceiling": "50000", "available": "49000" }
}

user is your account's own limit (null when it has none) and workspace is the limit shared by the main account and its sub-accounts. An early settlement needs room in both.