Hosted Checkout
With the hosted checkout you create a checkout session for an order, send your customer to an Avenia payment page, and receive the result by webhook. The customer types the card on Avenia's page, inside the payment provider's secure fields: card data never touches your servers, and you stay out of PCI-DSS card-data scope.
Your backend Avenia Your customer
------------ ------ -------------
0. GET /quote/fixed-rate ---> prices the sale
(BRL CARD) <--- { quoteToken, ... }
1. POST /checkout-sessions ---> creates the session
<--- { id, sessionToken, expiresAt }
2. builds the page URL
with the sessionToken -------------------------------> 3. opens the page,
types the card
(3DS if required)
4. authorizes and
captures the payment <---
5. page shows the result,
then sends the customer back
6. receives the webhook <--- ACQUIRING-PAYMENT-CAPTURED
and fulfils the order
- The webhook is the source of truth. Fulfil an order when
ACQUIRING-PAYMENT-CAPTUREDarrives, never because a customer reached your site. - Quote first. Each session is opened from a card sale quote: the quote sets the amount, what you receive and in which currency, and the session lives as long as the quote, 5 minutes. See the quote token.
- One quote, one session. The
quoteTokenis the idempotency key of the session.externalIdis your own order reference: optional, not unique, only stored and returned. - Read the overview first for the set-up,
subAccountId, units and authentication.
Create a checkout session
Endpoint
Parameters
Query
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | No | Sell as this sub-account instead of your main account. |
Body: required
| Field | Type | Description |
|---|---|---|
quoteToken | string | The quoteToken of a card sale quote of the account that sells. The sale's amount is the quote's inputAmount, and it is paid in the quote's output currency. See the quote token. Your per-payment limit is not checked here: a session above it is created, and the page refuses it when the customer pays, with no payment and no webhook. Keep your quotes under the limit (a sandbox account's is R$ 5,000.00, "5000.00"). |
currency | string | BRL. Any other currency is refused with 400 only BRL is accepted as the sale currency. |
country | string | BR. |
language | string | A BCP 47 tag, for example pt-BR, en-US or es-ES. Drives the card form and the 3D Secure screen. |
payerEmail | string | A bare address (a@b.com, not Name <a@b.com>). Card networks require it. |
payerName | string | The customer's name. |
payerTaxId | string | The customer's CPF or CNPJ, digits only. |
successUrl | string | https:// only, on one of your allowedRedirectDomains. Where the page sends the customer back after the payment. |
cancelUrl | string | https:// only, on one of your allowedRedirectDomains. |
Body: optional
| Field | Type | Description |
|---|---|---|
externalId | string | Your own order reference, up to 68 characters. Not unique, and not part of the request compared on a repeat: it is only stored and returned on reads and webhooks, so you can match the sale to your order. |
beneficiaryWalletId | string | Where this sale is paid, as a ticket's beneficiaryWalletId for a blockchain output: the id of one of your beneficiary wallets, on the chain of the output of the sale's quote. Required when that output is on a blockchain. When it is INTERNAL, leave it out: the sale is paid to your account's balance. See settling a sale to a wallet. |
saveCard | object | {"customerReference": "..."}: offers the customer to keep the card. See Saved Cards. |
savedCards | object | {"customerReference": "..."}: offers a signed-in customer the cards they saved. See Saved Cards. |
The whole body must be under 4 KB. A field the route does not take is refused: there is no amount field, and sending one is refused with 400 InvalidFieldError: amount is invalid.
The quote token
Before you create the session, quote the sale with GET /v2/account/quote/fixed-rate and inputCurrency=BRL, inputPaymentMethod=CARD, inputAmount = the order's amount in BRL, and the output you want to receive (see card sale quotes). Selling for a sub-account, quote with the same subAccountId. Then send the quote's quoteToken:
- The quote is the price of the sale. The amount is its
inputAmount(whole cents), the MDR itsIn Fee, and what you receive itsoutputAmount, in itsoutputCurrency, on itsoutputPaymentMethod: your account's balance forINTERNAL, or thebeneficiaryWalletIdyou name for a blockchain (see settling a sale to a wallet). The main account's markup on the sale is the quote'sMarkup Fee. - The session lasts as long as the quote: 5 minutes. Its
expiresAtis the quote's. - A token opens one session. It is the idempotency key of the call: see retries. For a new session, quote again.
- An expired quote stops the payment. A payment that starts after the quote expired is refused with
QUOTE_EXPIRED: on the page, the customer is toldthis price has expired -- please return to the store and start the purchase again(409,{"code": "QUOTE_EXPIRED", "message": "..."}), and nothing is charged. To sell, quote again and create a new session with the newquoteToken. A payment that started before the quote expired goes on, through 3D Secure and the capture, even past the 5 minutes.
| Status | error | Cause |
|---|---|---|
| 400 | InvalidFieldError: quoteToken is invalid, "extraInfo": "required: a CARD quote's token" | No quoteToken. |
| 400 | InvalidFieldError: quoteToken is invalid, "extraInfo": "it must be an unexpired CARD quote of this account, from BRL CARD to BRLA, USDC or USDT" | The token is unreadable, another account's, not a card sale quote, or expired and not yet used. |
| 400 | InvalidFieldError: quoteToken is invalid, "extraInfo": "the card price changed since the quote: quote the sale again" | Your card price changed after the quote. |
| 400 | InvalidFieldError: quoteToken is invalid, "extraInfo": "its markup on this amount is above the markup Avenia allows for this workspace" | The quote's markup is above your workspace's markup cap. Quote again with a smaller markup. |
| 400 | InvalidFieldError: quoteToken is invalid, "extraInfo": "its amount must be at least <minimum>: a smaller sale does not cover this account's charges on it (MDR, markup and reserve) and could never be settled" | The quoted amount is too small to settle. Quote at least <minimum>. |
| 409 | this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new one | The token was already used by another request. See retries. |
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/acquiring/checkout-sessions" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"externalId": "order-10045",
"quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XXXX.XXXX",
"currency": "BRL",
"country": "BR",
"language": "pt-BR",
"payerEmail": "customer@example.com",
"payerName": "Maria Silva",
"payerTaxId": "12345678901",
"successUrl": "https://shop.example.com/orders/10045/thanks",
"cancelUrl": "https://shop.example.com/orders/10045/payment-failed",
"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c"
}'
Response
201 Created:
{
"id": "0b9c2f44-1d7e-4f0a-a3c2-5b8e9d1f6a20",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"externalId": "order-10045",
"amount": "150",
"currency": "BRL",
"country": "BR",
"language": "pt-BR",
"status": "CREATED",
"sessionToken": "q3J9xG0bKk2mWc1yTzVf8Lr5Hn7Pd4Sa6Ue0Bo2Ci1",
"successUrl": "https://shop.example.com/orders/10045/thanks",
"cancelUrl": "https://shop.example.com/orders/10045/payment-failed",
"expiresAt": "2026-10-08T15:05:00Z",
"createdAt": "2026-10-08T15:00:02Z",
"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c",
"walletAddress": "0x4c7e2a91d3b05f68e1a2c4d6b8f0a3e5c7d9b1f2",
"walletChain": "POLYGON",
"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"
}
}
sessionTokenis a credential. Whoever has it can open the page and see the purchase. Give it only to the customer who is paying, and keep it out of your logs.- The session expires with its quote, 5 minutes after the quote (
expiresAt). After that the page refuses to open, and a payment it had not started is refused withQUOTE_EXPIRED: quote again and create a new session with the newquoteToken. amountis the quote'sinputAmount.quoteis the quote the session was opened from:outputCurrency,outputPaymentMethodandoutputAmount(what you receive, and where),rate(BRL per 1 unit ofoutputCurrency, read aspairNamesays;"1"forBRLA), its fees in BRL (inputFeeis the MDR, thenconversionFee,markupFee,outFee,gasFee) and itsexpiresAt. The same object is the payment'squote.userIdis the id of the account that sells.externalIdis the reference you sent,""when you sent none.beneficiaryWalletIdis the wallet the sale is paid to, andwalletAddressandwalletChainare that wallet's address and chain, read when the session is created. All three are""when the sale is paid to your account's balance. See settling a sale to a wallet.
Retries are safe
The quoteToken makes the call idempotent: one token opens one session.
| You send | You get |
|---|---|
A new quoteToken | 201 and a new session |
A quoteToken you already used, with the same request | 200 and the existing session, unchanged |
A quoteToken you already used, with the same request, after its quote expired | 200 and the existing session, unchanged. The page no longer opens once the session's expiresAt has passed: to sell, quote again. |
A quoteToken you already used, with the same request but another externalId | 200 and the existing session, unchanged: it keeps the first request's externalId. |
A quoteToken you already used, with other terms (a URL, the payer, the wallet, and so on) | 409 this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new one |
A quoteToken that already opened a server-to-server payment or a saved-card charge | 409 this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new one: one token opens one sale, on one entry point. |
externalId is not a key: sessions opened from different quotes may carry the same externalId, or none.
If a request times out, repeat it with the same body. A repeat never updates the session.
Read or cancel a session
The cancel call takes no body (an empty {} is accepted). Both answer with the session object above.
status | Meaning |
|---|---|
CREATED | Created, the customer has not opened the page yet. |
CONSUMED | The customer opened the page. |
CANCELED | You cancelled it. |
- A session can only be cancelled while it is
CREATED, before the customer opens the page. After that the call answers409. - A session past
expiresAtmay still readCREATED. CompareexpiresAtwith the current time. - The session does not tell you whether the payment succeeded. That comes by webhook, or from
GET /payments/{payment-id}.
The hosted payment page
Build the page URL with the session's sessionToken in place of {session-token}, and send your customer to it, by a redirect or in a new tab:
https://checkout.sandbox.brla.digital:10953/checkout/{session-token}
Sandbox does not answer on 443: the payment page is on port 10953, and the API on 10952.
The customer sees:
- The amount and a card form: card number, expiry, security code and the name printed on the card (required). The card number and security code are encrypted in the customer's browser before they leave it.
- If the session offers them, an unticked checkbox to save the card and the customer's saved cards to choose from.
- An installments selector, when your account offers more than one (debit cards pay in one), and a Pay button.
- If the issuer asks for 3D Secure, the bank's challenge, inside the page.
- The result, then a short pause before the page sends the customer back to you.
A declined customer gets no reason, by design: decline reasons help card-testing fraud. The reason reaches you in the webhook.
After the payment
The page shows the result for a few seconds and sends the customer to your successUrl when the payment was approved, or to your cancelUrl when it was not. The redirect goes exactly to the URL you sent, with no parameters added: put your own order id in those URLs.
- Fulfil the order from the webhook. A customer who closes the tab never reaches either URL, and a URL can be opened by anyone who has it.
- If the customer reaches
successUrlbefore the webhook, show "confirming your payment" and wait forACQUIRING-PAYMENT-CAPTURED.
Trying another card
After a plain decline, in which no money was authorized, the page can let the customer try another card on the same payment, while the session is open and the page's attempts for a session are not used up. Each decline is announced with ACQUIRING-PAYMENT-DECLINED, and the same payment (same id) can still end CAPTURED with the next card.
So on a hosted session DECLINED is the outcome of one attempt, not the end of the sale. The final outcomes are:
ACQUIRING-PAYMENT-CAPTURED: paid. Fulfil the order, once.- The session ending without a capture: it passes
expiresAt(a session the customer opened can no longer be cancelled), and the last decline stands.
Do not open a new session for the order while the first session is open: if the customer pays on the first one after you opened the second, the order is paid twice. Wait for CAPTURED, or for the session to end, and only then quote again and create a new session with the new quoteToken. Every outcome reaches you by webhook.