Card Acquiring Webhooks
Card acquiring events arrive at the same webhook URLs as every other Avenia event, under their own subscriptions: one per object, as tickets arrive under TICKET. The webhook is the source of truth for a payment's final state, especially after 3D Secure: fulfil an order on ACQUIRING-PAYMENT-CAPTURED, never because a customer reached your site.
Register your URL
You can register up to 3 URLs per account. The URL must be https.
{
"webhookUrl": "https://api.example.com/webhooks/avenia",
"subscriptions": [
"ACQUIRING-PAYMENT",
"ACQUIRING-SETTLEMENT",
"ACQUIRING-REFUND",
"ACQUIRING-RECEIVABLE",
"ACQUIRING-EARLY-SETTLEMENT",
"DISPUTE"
]
}
Response: 201 {"webhookId": "..."}. Manage registrations with GET, PATCH and DELETE as in Webhook Management. A webhook subscribed to * receives the acquiring events too.
You subscribe to an object, and receive every event of it: the event's own name is in data.type. Any other subscription name is refused with 400 InvalidFieldError: subscriptions is invalid.
Card disputes are not an acquiring subscription: they arrive under DISPUTE, with PIX disputes. See dispute events.
| Subscription | Events (data.type) | Sent when |
|---|---|---|
ACQUIRING-PAYMENT | ACQUIRING-PAYMENT-AUTHORIZED, -CAPTURED, -DECLINED, -BLOCKED, -ERROR, -EXPIRED, -CANCELED, -REFUNDED, -VERIFIED | A payment reaches that status: see payment events. |
ACQUIRING-SETTLEMENT | ACQUIRING-SETTLEMENT-PAID, ACQUIRING-SETTLEMENT-HELD | A settlement is paid, or its payout did not go out. |
ACQUIRING-REFUND | ACQUIRING-REFUND-PENDING-APPROVAL, ACQUIRING-REFUND-REJECTED | A refund above your cover waits for approval, or is turned down. |
ACQUIRING-RECEIVABLE | ACQUIRING-RECEIVABLE-OPENED, -DEBITED, -RESOLVED | A debt you owe is opened, moves, or ends: see debt events. |
ACQUIRING-EARLY-SETTLEMENT | ACQUIRING-EARLY-SETTLEMENT-DECIDED | An early settlement you asked for is executed. |
What arrives
A POST to your URL. The envelope is the same for every event; data depends on the event.
{
"event": {
"id": "5e2a7c10-93f4-4b1e-8d61-2c0f7a9b3e55",
"accountId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"subscription": "ACQUIRING-PAYMENT",
"data": {
"id": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"userId": "a91d3c47-5e20-4f8b-9c16-7d2e0b4a8f13",
"checkoutSessionId": "3f6a9c2e-8b1d-4e7f-a05c-6d2b9e4f1a87",
"externalId": "order-10045",
"status": "CAPTURED",
"amount": "150",
"currency": "BRL",
"country": "BR",
"installments": 1,
"paymentMethod": "CREDIT",
"authorizedAmount": "150",
"capturedAmount": "150",
"refundedAmount": "0",
"chargedBackAmount": "0",
"disputeWindowClosesAt": "2027-04-08T15:02:12Z",
"createdAt": "2026-10-08T15:02:11.482Z",
"capturedAt": "2026-10-08T15:02:12Z",
"savedCardId": "",
"card": { "brand": "VISA", "last4": "0002" },
"declineBucket": "",
"failureCode": "",
"quote": {
"outputCurrency": "USDC",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "26.597222",
"rate": "5.4",
"pairName": "USDCBRL",
"inputFee": "4.875",
"conversionFee": "1.5",
"markupFee": "0",
"outFee": "0",
"gasFee": "0",
"expiresAt": "2026-10-08T15:05:00Z"
},
"receivables": [
{ "installmentNumber": 1, "expectedDate": "2026-11-09T00:00:00Z", "amount": "137.62", "expectedAmount": "25.221772" }
],
"beneficiaryWalletId": "",
"walletAddress": "",
"walletChain": "",
"type": "ACQUIRING-PAYMENT-CAPTURED"
},
"createdAt": "2026-10-08T15:02:13.105Z"
}
}
event.subscriptionis the subscription (ACQUIRING-PAYMENT) anddata.typethe event (ACQUIRING-PAYMENT-CAPTURED): act ondata.type.event.idis unique per event.event.accountIdis the account the event is about: your account, or the sub-account's id when the sale was made for a sub-account. A payment'sdatanames it indata.userId.- Events leave within about a minute of the change.
Payment events
data is the payment, with the fields of GET /payments/{payment-id} except refunds:
data.idis the payment id, the sameidthe payment call returned. You need it for refunds. Match the payment to your order withdata.externalId.data.userIdis the account the sale belongs to, anddata.checkoutSessionIdthe checkout session the payment was made in.data.capturedAtis when the payment was captured,""before the capture.data.subStatusappears on some failures: see Errors and Decline Codes.data.failureCodeis why the payment endedBLOCKED,DECLINEDorERROR,""on every other event. Match on it rather than onsubStatus.data.declineBucketis set when the payment is declined: see decline buckets.""on every other event.data.savedCardIdis the id of the card this payment saved for future charges, or""when it saved none.data.cardis the card's networkbrandandlast4digits, both""when unknown (for example on a payment refused before the card was read).data.quoteanddata.receivablesare onACQUIRING-PAYMENT-CAPTUREDonly: the quote the sale was opened from, which fixes its rate and every fee (the MDR isinputFee, the main account's markupmarkupFee), and what each installment is expected to deliver. See the price of a sale.data.beneficiaryWalletId,data.walletAddressanddata.walletChainname the wallet the sale is paid to, all""when it is paid to your account's balance.
| Event | Meaning | What to do |
|---|---|---|
ACQUIRING-PAYMENT-CAPTURED | Paid. | Fulfil the order. |
ACQUIRING-PAYMENT-AUTHORIZED | Approved by the issuer, capture still pending. Usually followed by CAPTURED or CANCELED. | Wait for the next event. |
ACQUIRING-PAYMENT-DECLINED | Refused by the issuer or by fraud screening. | Server-to-server: the payment is over; offer a new attempt (a new quote), with the same card if declineBucket is RETRYABLE, with another card if it is TERMINAL. Hosted page: this is one attempt only: the customer may try another card on the same payment, which can still reach CAPTURED. Do not open a new session until the first one has ended (Trying another card). |
ACQUIRING-PAYMENT-BLOCKED | Refused by Avenia before reaching the issuer (failureCode USER_BLOCKED). | Offer a new attempt; contact Avenia if unexpected. |
ACQUIRING-PAYMENT-ERROR | Technical failure; no money moved. subStatus and failureCode are always INTERNAL_ERROR. | Offer a new attempt. |
ACQUIRING-PAYMENT-EXPIRED | The customer abandoned the payment or the 3D Secure challenge. | Nothing to do. |
ACQUIRING-PAYMENT-CANCELED | Authorization voided before capture; the customer was never charged. | Treat as not paid. |
ACQUIRING-PAYMENT-REFUNDED | Refunded, in part (status: "PARTIALLY_REFUNDED", with the running refundedAmount) or in full (REFUNDED). | Mark as refunded. |
ACQUIRING-PAYMENT-VERIFIED | A zero-amount verification of a card succeeded. | Nothing was charged. |
Only CAPTURED means money. Pending states (waiting for 3D Secure, waiting for the acquirer) produce no event, and neither does a dispute outcome on the payment: those use the dispute events.
A captured payment can be refunded by Avenia. Some fraud checks run after the capture. When one fails, Avenia refunds the payment to the card on its own and you receive ACQUIRING-PAYMENT-REFUNDED without having asked for a refund.
Settlement events
ACQUIRING-SETTLEMENT-PAID and ACQUIRING-SETTLEMENT-HELD. data:
| Field | Meaning |
|---|---|
id, settlementType, status, paymentMethod | The settlement, as in GET /settlements/{settlement-id}. |
failureCode | Always present, and "" on both events. A settlement that ends FAILED sends no event: read the settlement for its failureCode. |
grossAmount, netAmount | What the settlement covers, and what it pays after fees. |
payoutCurrency, payoutAmount, walletChain | What is paid: the currency (BRLA, USDC or USDT), the amount as a decimal string, and the chain. |
walletAddress, txHash, paidAt | PAID only. Where, the transaction and when. A settlement to a wallet named on the sale carries its walletAddress on every event. |
beneficiaryWalletId | The wallet the settlement pays, "" when it pays your account. |
releasedInstallments | A DEFERRED_RELEASE: the installments it pays, each {paymentId, installmentNumber, releasedAmount}. |
releasedReserve | A RESERVE_RELEASE: the tranches it gives back, each {origin, settlementId, disputeId, heldAt, releasableAt, releasedAmount}. |
receivableOffsetAmount, offsetReceivables | The debt this settlement netted off, and which debts: each {receivableId, origin, paymentId, receivableOffsetAmount}. |
earlySettlement | An EARLY_SETTLEMENT: the early settlement it pays, with its fees and the installments it took. |
ACQUIRING-SETTLEMENT-HELD means the payout did not go out; the event never says why.
Dispute events
Card disputes arrive under the DISPUTE subscription, shared with PIX disputes, as CARD-DISPUTE-<STATUS>: CARD-DISPUTE-RECEIVED, -PENDING_REVIEW, -WON, -LOST, -ACCEPTED and -PREVENTED, one each time a dispute reaches that status. data.cardDispute carries the dispute. CARD-DISPUTE-WON is the only way you learn of a win. The payload is in Webhook Events.
Refund events
ACQUIRING-REFUND-PENDING-APPROVAL and ACQUIRING-REFUND-REJECTED. data: id (the refund), paymentId, amount, externalId, status, approvalExpiresAt (while it waits) and failureCode: PAYMENT_NOT_REVERSIBLE when the payment stopped being reversible while the refund waited, "" otherwise (see refund failure codes). A rejection never says why a person rejected it. An approved refund announces itself as ACQUIRING-PAYMENT-REFUNDED.
Debt events
A debt arises when a refund exceeds your cover, from a chargeback, or from the FX difference of a refund or chargeback of a sale paid out in USDC or USDT. These events are of record: they document money taken from your balance.
ACQUIRING-RECEIVABLE-OPENEDandACQUIRING-RECEIVABLE-RESOLVED:id,origin(CHARGEBACK,REFUND_AFTER_PAYOUT,ADJUSTMENTorFX_DIFFERENCE: what buying back the USDC or USDT of a refunded or charged-back sale cost above its locked rate),status,amount,outstandingAmount,currency,paymentId,disputeId,refundId(""where the origin has none),openedAtand, onRESOLVED,resolution(RECOVERED,WRITTEN_OFForREVERSED) andresolvedAt.ACQUIRING-RECEIVABLE-DEBITED: one movement on a debt.receivableId,movementId,movementType,source,direction(DEBITtook from your balance toward the debt,RETURNgave it back: a won dispute reverses a pull),amount(always positive),currency,fxRate,settlementId,outstandingAmountandat. A burn from your account's token balance hasmovementTypeSWEEPandsourceUSER_WALLET, withcurrencythe token burned (BRLfor BRLA) andfxRateits BRL price: see what a refund or chargeback takes.
Early settlement events
ACQUIRING-EARLY-SETTLEMENT-DECIDED: an early settlement was executed. It is sent only then: nothing is settled early by itself. It carries the early settlement'searlySettlementId,earlySettlementDate,beneficiary,userId(the account whose sales the lines are of), its rates (aveniaMonthlyPctandmainMonthlyPct), its sums (principalAmount,aveniaFee,mainFee,fundedAmount), itslinesandsettlementId, the settlement that pays aSUBearly settlement (""on aMAINone). A main account's early settlement over several sub-accounts' sales is announced once per sub-account, each with that sub-account's lines and sums: the whole early settlement isGET /early-settlements/{early-settlement-id}.
Verifying the signature
Every delivery has a Signature header: base64 of an RSA-PSS / SHA-256 signature over the raw request body. Verify it with Avenia's public key, fetched once from GET /v2/public-key (no authentication; the response is {"publicKey": "<PEM>"}) and cached. Verify against the raw bytes as received, before any JSON parsing. The full walkthrough, with code, is Verifying Webhook Authenticity.
Handling deliveries
- Verify the signature, and reject anything that fails.
- Answer
2xximmediately, within a few seconds, then process asynchronously. - Deduplicate on
event.id. The same event can arrive more than once; process it once. - Do not assume order. Within one payment, apply an event only if it moves the payment forward (for example, ignore an
AUTHORIZEDarriving afterCAPTURED).
Network failures (timeout, connection refused) are retried a few times; an error status from your server is not. Answer 2xx as soon as the signature checks out, and use the events API below to catch anything you missed.
Catching up on missed events
subscriptiontakes a subscription, such asACQUIRING-PAYMENT, not an event: tell the events apart bydata.type.createdAfterandcreatedBeforeare Unix time in milliseconds.- The response is
{"events": [...], "cursor": "..."}: newest first, at most 100 events per page. Passcursorback to get the next page. - Only events that were sent to a webhook URL you had registered are listed: an event created before you registered one is not.
- Sub-account events are not in the main account's list. Add
?subAccountId={sub-account-id}to read a sub-account's. - Each event has the same shape as a delivery's
event.
Use it for a periodic reconciliation (for example, every 15 minutes for the last hour), or to look up an order you never heard about. For one payment and its refunds, GET /payments/{payment-id} is the answer.