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.

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-CAPTURED arrives, 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 quoteToken is the idempotency key of the session. externalId is 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​

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/checkout-sessions

Parameters​

Query

FieldTypeRequiredDescription
subAccountIdstringNoSell as this sub-account instead of your main account.

Body: required

FieldTypeDescription
quoteTokenstringThe 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").
currencystringBRL. Any other currency is refused with 400 only BRL is accepted as the sale currency.
countrystringBR.
languagestringA BCP 47 tag, for example pt-BR, en-US or es-ES. Drives the card form and the 3D Secure screen.
payerEmailstringA bare address (a@b.com, not Name <a@b.com>). Card networks require it.
payerNamestringThe customer's name.
payerTaxIdstringThe customer's CPF or CNPJ, digits only.
successUrlstringhttps:// only, on one of your allowedRedirectDomains. Where the page sends the customer back after the payment.
cancelUrlstringhttps:// only, on one of your allowedRedirectDomains.

Body: optional

FieldTypeDescription
externalIdstringYour 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.
beneficiaryWalletIdstringWhere 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.
saveCardobject{"customerReference": "..."}: offers the customer to keep the card. See Saved Cards.
savedCardsobject{"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 its In Fee, and what you receive its outputAmount, in its outputCurrency, on its outputPaymentMethod: your account's balance for INTERNAL, or the beneficiaryWalletId you name for a blockchain (see settling a sale to a wallet). The main account's markup on the sale is the quote's Markup Fee.
  • The session lasts as long as the quote: 5 minutes. Its expiresAt is 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 told this 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 new quoteToken. A payment that started before the quote expired goes on, through 3D Secure and the capture, even past the 5 minutes.
StatuserrorCause
400InvalidFieldError: quoteToken is invalid, "extraInfo": "required: a CARD quote's token"No quoteToken.
400InvalidFieldError: 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.
400InvalidFieldError: quoteToken is invalid, "extraInfo": "the card price changed since the quote: quote the sale again"Your card price changed after the quote.
400InvalidFieldError: 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.
400InvalidFieldError: 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>.
409this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new oneThe token was already used by another request. See retries.

Request example​

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

JSON
{
"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"
}
}
  • sessionToken is 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 with QUOTE_EXPIRED: quote again and create a new session with the new quoteToken.
  • amount is the quote's inputAmount.
  • quote is the quote the session was opened from: outputCurrency, outputPaymentMethod and outputAmount (what you receive, and where), rate (BRL per 1 unit of outputCurrency, read as pairName says; "1" for BRLA), its fees in BRL (inputFee is the MDR, then conversionFee, markupFee, outFee, gasFee) and its expiresAt. The same object is the payment's quote.
  • userId is the id of the account that sells.
  • externalId is the reference you sent, "" when you sent none.
  • beneficiaryWalletId is the wallet the sale is paid to, and walletAddress and walletChain are 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 sendYou get
A new quoteToken201 and a new session
A quoteToken you already used, with the same request200 and the existing session, unchanged
A quoteToken you already used, with the same request, after its quote expired200 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 externalId200 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 charge409 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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/checkout-sessions/{session-id}
POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/checkout-sessions/{session-id}/cancel

The cancel call takes no body (an empty {} is accepted). Both answer with the session object above.

statusMeaning
CREATEDCreated, the customer has not opened the page yet.
CONSUMEDThe customer opened the page.
CANCELEDYou cancelled it.
  • A session can only be cancelled while it is CREATED, before the customer opens the page. After that the call answers 409.
  • A session past expiresAt may still read CREATED. Compare expiresAt with 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}
The port is part of the URL

Sandbox does not answer on 443: the payment page is on port 10953, and the API on 10952.

The customer sees:

  1. 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.
  2. If the session offers them, an unticked checkbox to save the card and the customer's saved cards to choose from.
  3. An installments selector, when your account offers more than one (debit cards pay in one), and a Pay button.
  4. If the issuer asks for 3D Secure, the bank's challenge, inside the page.
  5. 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 successUrl before the webhook, show "confirming your payment" and wait for ACQUIRING-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.