Card Acquiring Overview
Card acquiring lets your account, or one of your sub-accounts, charge credit and debit cards in Brazilian reais (BRL) and be paid in BRLA, USDC or USDT. Avenia authorizes and captures the payment, screens it for risk, settles it to a wallet you choose and reports every step by webhook.
Card acquiring is available in the sandbox for now. Sandbox moves no real money and authorizes no real cards: use the test cards. The routes are not served in production yet.
Two ways to take a payment
| Hosted checkout | Server-to-server | |
|---|---|---|
| Who collects the card | Avenia's payment page, in secure fields | Your servers, encrypted on the way in |
| PCI-DSS scope | None for card data | You must be PCI-DSS certified |
| What you call | POST /v2/account/acquiring/checkout-sessions, then send the customer to the page | POST /v2/account/acquiring/payments, through an encryption relay |
| 3D Secure | Runs inside the page | You redirect the cardholder's browser |
| Result | Webhook | Synchronous answer, then webhook |
Start with the hosted checkout unless you already hold a PCI-DSS attestation. Both ways share everything after the payment: refunds, disputes, settlement, the reads and the webhooks.
How a payment moves
- You quote the sale with a card sale quote, then create a payment (a checkout session for the hosted page, or the payment itself) with its
quoteTokenand, if you like, anexternalId, your own order id. The quote sets the amount and what you receive, and lasts 5 minutes. - The issuer authorizes it, with a 3D Secure challenge when the issuer or the sale asks for one.
- The payment is captured.
ACQUIRING-PAYMENT-CAPTUREDis the only event that means money: fulfil the order on it. - A settlement pays you, in the output currency of the sale's quote, to your account's balance or to the wallet the sale names. Credit card sales in installments are paid as the acquirer pays each installment, unless you settle them early on demand.
- Refunds go back to the card. A cardholder can also open a dispute (a chargeback), which you contest or accept.
Payment statuses
status is on every payment answer and read. The ones that announce themselves have a webhook.
status | Meaning | Event |
|---|---|---|
PENDING_3DS | The issuer wants a challenge: the cardholder must complete it. | None |
PENDING_PROVIDER, PENDING_REVIEW | Still being decided. | None |
AUTHORIZED | Approved by the issuer, capture pending. | ACQUIRING-PAYMENT-AUTHORIZED |
PARTIALLY_CAPTURED | Part of the authorized amount was captured. It is not announced by itself: the total arrives with ACQUIRING-PAYMENT-CAPTURED. | None |
CAPTURED | Paid. | ACQUIRING-PAYMENT-CAPTURED |
VERIFIED | A zero-amount verification of a card: nothing was authorized or captured. | ACQUIRING-PAYMENT-VERIFIED |
DECLINED | Refused by the issuer or by fraud screening. | ACQUIRING-PAYMENT-DECLINED |
BLOCKED | Refused by Avenia before it reached the issuer. | ACQUIRING-PAYMENT-BLOCKED |
ERROR | Technical failure; no money moved. | ACQUIRING-PAYMENT-ERROR |
EXPIRED | The customer abandoned the payment or the 3D Secure challenge. | ACQUIRING-PAYMENT-EXPIRED |
CANCELED | The authorization was voided before capture. | ACQUIRING-PAYMENT-CANCELED |
PARTIALLY_REFUNDED, REFUNDED | Part of, or all of, the captured amount went back to the card. | ACQUIRING-PAYMENT-REFUNDED |
IN_DISPUTE, CHARGEBACK, CHARGEBACK_PREVENTED | A dispute is open or was decided. | CARD-DISPUTE-<STATUS>, under the DISPUTE subscription |
A failed payment also carries a failureCode, and a decline a declineBucket: see Errors and Decline Codes.
Settlement, installments and early settlement
- Payout currency and wallet. Each sale is paid in the output currency of its quote (
BRLA,USDCorUSDT), to your account, or to the wallet you name on the sale when its quote's output is on a blockchain. - MDR and reserve. Avenia keeps the MDR (a percentage of the captured amount plus a fixed fee) and may hold part of each sale as a rolling reserve. Every payment answer carries the sale's
quote, whoseinputFeeis the MDR, and itsreceivables: see the price of a sale. - Installments. A credit card payment can be split in up to your account's maximum number of installments (
maxInstallmentsinGET /config). The cardholder pays no interest and you receive each installment's share as it falls due. Debit cards pay in one. - Early settlement. A sale is paid as the acquirer pays its installments. Nothing is settled early by itself: you bring forward money that is still waiting for the acquirer on demand, an account's own delivery or the main account's markup: see Early settlements.
- Deferred money. What waits for the acquirer to pay an installment is your
deferredPayablein the balance.
Before you start
Set-up. Avenia configures card acquiring for your account, and for each sub-account you sell for, after onboarding. The configuration (statement descriptor, allowed return domains and maximum installments) is not written through the API. Read it with:
{
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"statementDescriptor": "MYSTORE",
"allowedRedirectDomains": ["shop.example.com"],
"maxInstallments": 12,
"createdAt": "2026-10-01T12:00:00Z"
}
| Field | Meaning |
|---|---|
userId | The id of the account (or sub-account) the configuration belongs to. |
statementDescriptor | The name on the cardholder's card statement. |
allowedRedirectDomains | The domains your successUrl and cancelUrl must be on. Tell Avenia the domains of your pages. |
maxInstallments | The ceiling for installments. |
The seller is the account that makes the call. There is no merchant id to send.
Several stores. To act for a sub-account, add ?subAccountId={sub-account-id} to any acquiring route, including the POSTs. A sub-account only sees its own payments, settlements, disputes and saved cards, and must be one of yours. subAccountId is always a query parameter, never a body field (except where a page says so). Webhooks for every sub-account arrive at the main account's URLs, with event.accountId set to the sub-account's id.
Authentication. Acquiring uses the same authentication as the rest of the API. A server integration should sign its requests with an API key; the curl examples in this section show a JWT in Authorization: Bearer <token> for brevity, and a JWT that creates something needs TOTP MFA. Refunds, dispute decisions and early settlements need an admin access. Refunds and accepting a dispute can also wait for multi-approval when your access is a multi-sig requester.
Conventions
- Money is a decimal in BRL. Send an amount or a rate as a plain decimal, in a JSON number or a string: digits and an optional fraction after a dot, at most 20 digits before the point and 18 after.
150.5and"150.50"are the same amount. Exponent notation (1e2,1.05e1) is refused, also as a JSON number, and no amount or rate here takes a minus sign. As on quotes, an amount takes at most 2 decimal places in a fiat currency and 6 in any other; every amount you send here is in BRL, so 2. A value outside these rules is refused, never rounded, with400 InvalidFieldErrornaming the field and the rule inextraInfo(for examplemust have at most 2 decimal places); a value that is not a number at all ("ten","") is refused with400 InvalidBodyError. - Answers and webhooks write amounts and rates as decimal strings, without trailing zeros: R$ 150.00 reads
"150", R$ 10.50 reads"10.5"and a rate of 2.99% reads"0.0299". Payout amounts and conversion rates keep their full precision ("26.044733"), and a settlement'sfxRateisnullwhen nothing is converted. Compare amounts as numbers, not as text. - Field names are camelCase, and dates are RFC 3339 instants unless a page says otherwise.
- The
quoteTokenis the idempotency key of a sale. One quote token opens one payment, checkout session or saved-card charge; the same request with it again returns that sale, even after the quote expired, and the same token with other terms, or on another entry point, is409.externalIdis your own order reference: optional, up to 68 characters, not unique, only stored and returned on reads and webhooks. It is not compared on a repeat: a repeat that differs only byexternalIdreturns the sale with the first request'sexternalId. A refund's idempotency key is theX-API-IdempotencyKeyheader, required on the refund call (without it,400); itsexternalIdis only your own label. - Unknown fields are refused. A body field the route does not take answers
400 InvalidFieldError: <field> is invalidwith"extraInfo": "not a field of this request", and so does a query parameter the route does not list. - Bodies are at most 4 KB, except the dispute evidence upload.
- Identifiers are yours to read, never to parse. Ids are UUIDs. A resource of another account or sub-account answers
404, exactly as one that does not exist.
In this section
| Page | What it covers |
|---|---|
| Hosted Checkout | Checkout sessions and the Avenia payment page. |
| Server-to-Server Payments | Encrypted card data, signing, 3D Secure, installments. |
| Saved Cards | Keeping a card and charging it again. |
| Refunds and Cancellations | Returning money, refunds that wait for approval. |
| Disputes (Chargebacks) | What a chargeback does to your money. Reading, contesting and accepting one: Card Disputes. |
| Settlement and Balance | The price of a sale, settling a sale to a wallet, settlements and the balance. |
| Schedule, Statement and Timeline | What you will receive, how your money moved, one payment step by step. |
| Early settlements | Bringing forward money that waits for the acquirer, on demand. |
| Card Acquiring Webhooks | Every event and its payload. |
| Errors and Decline Codes | Errors, failure codes and what to tell the customer. |
| Sandbox: Test Cards and Scenarios | Test cards, 3D Secure, simulated chargebacks and settlements. |