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.

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.

Sandbox only

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 checkoutServer-to-server
Who collects the cardAvenia's payment page, in secure fieldsYour servers, encrypted on the way in
PCI-DSS scopeNone for card dataYou must be PCI-DSS certified
What you callPOST /v2/account/acquiring/checkout-sessions, then send the customer to the pagePOST /v2/account/acquiring/payments, through an encryption relay
3D SecureRuns inside the pageYou redirect the cardholder's browser
ResultWebhookSynchronous 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​

  1. 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 quoteToken and, if you like, an externalId, your own order id. The quote sets the amount and what you receive, and lasts 5 minutes.
  2. The issuer authorizes it, with a 3D Secure challenge when the issuer or the sale asks for one.
  3. The payment is captured. ACQUIRING-PAYMENT-CAPTURED is the only event that means money: fulfil the order on it.
  4. 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.
  5. 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.

statusMeaningEvent
PENDING_3DSThe issuer wants a challenge: the cardholder must complete it.None
PENDING_PROVIDER, PENDING_REVIEWStill being decided.None
AUTHORIZEDApproved by the issuer, capture pending.ACQUIRING-PAYMENT-AUTHORIZED
PARTIALLY_CAPTUREDPart of the authorized amount was captured. It is not announced by itself: the total arrives with ACQUIRING-PAYMENT-CAPTURED.None
CAPTUREDPaid.ACQUIRING-PAYMENT-CAPTURED
VERIFIEDA zero-amount verification of a card: nothing was authorized or captured.ACQUIRING-PAYMENT-VERIFIED
DECLINEDRefused by the issuer or by fraud screening.ACQUIRING-PAYMENT-DECLINED
BLOCKEDRefused by Avenia before it reached the issuer.ACQUIRING-PAYMENT-BLOCKED
ERRORTechnical failure; no money moved.ACQUIRING-PAYMENT-ERROR
EXPIREDThe customer abandoned the payment or the 3D Secure challenge.ACQUIRING-PAYMENT-EXPIRED
CANCELEDThe authorization was voided before capture.ACQUIRING-PAYMENT-CANCELED
PARTIALLY_REFUNDED, REFUNDEDPart of, or all of, the captured amount went back to the card.ACQUIRING-PAYMENT-REFUNDED
IN_DISPUTE, CHARGEBACK, CHARGEBACK_PREVENTEDA 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, USDC or USDT), 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, whose inputFee is the MDR, and its receivables: see the price of a sale.
  • Installments. A credit card payment can be split in up to your account's maximum number of installments (maxInstallments in GET /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 deferredPayable in 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:

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/config
JSON
{
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"statementDescriptor": "MYSTORE",
"allowedRedirectDomains": ["shop.example.com"],
"maxInstallments": 12,
"createdAt": "2026-10-01T12:00:00Z"
}
FieldMeaning
userIdThe id of the account (or sub-account) the configuration belongs to.
statementDescriptorThe name on the cardholder's card statement.
allowedRedirectDomainsThe domains your successUrl and cancelUrl must be on. Tell Avenia the domains of your pages.
maxInstallmentsThe 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.5 and "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, with 400 InvalidFieldError naming the field and the rule in extraInfo (for example must have at most 2 decimal places); a value that is not a number at all ("ten", "") is refused with 400 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's fxRate is null when 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 quoteToken is 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, is 409. externalId is 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 by externalId returns the sale with the first request's externalId. A refund's idempotency key is the X-API-IdempotencyKey header, required on the refund call (without it, 400); its externalId is only your own label.
  • Unknown fields are refused. A body field the route does not take answers 400 InvalidFieldError: <field> is invalid with "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​

PageWhat it covers
Hosted CheckoutCheckout sessions and the Avenia payment page.
Server-to-Server PaymentsEncrypted card data, signing, 3D Secure, installments.
Saved CardsKeeping a card and charging it again.
Refunds and CancellationsReturning money, refunds that wait for approval.
Disputes (Chargebacks)What a chargeback does to your money. Reading, contesting and accepting one: Card Disputes.
Settlement and BalanceThe price of a sale, settling a sale to a wallet, settlements and the balance.
Schedule, Statement and TimelineWhat you will receive, how your money moved, one payment step by step.
Early settlementsBringing forward money that waits for the acquirer, on demand.
Card Acquiring WebhooksEvery event and its payload.
Errors and Decline CodesErrors, failure codes and what to tell the customer.
Sandbox: Test Cards and ScenariosTest cards, 3D Secure, simulated chargebacks and settlements.