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 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.

POSThttps://api.sandbox.avenia.io:10952/v2/notifications/webhooks
JSON
{
"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.

SubscriptionEvents (data.type)Sent when
ACQUIRING-PAYMENTACQUIRING-PAYMENT-AUTHORIZED, -CAPTURED, -DECLINED, -BLOCKED, -ERROR, -EXPIRED, -CANCELED, -REFUNDED, -VERIFIEDA payment reaches that status: see payment events.
ACQUIRING-SETTLEMENTACQUIRING-SETTLEMENT-PAID, ACQUIRING-SETTLEMENT-HELDA settlement is paid, or its payout did not go out.
ACQUIRING-REFUNDACQUIRING-REFUND-PENDING-APPROVAL, ACQUIRING-REFUND-REJECTEDA refund above your cover waits for approval, or is turned down.
ACQUIRING-RECEIVABLEACQUIRING-RECEIVABLE-OPENED, -DEBITED, -RESOLVEDA debt you owe is opened, moves, or ends: see debt events.
ACQUIRING-EARLY-SETTLEMENTACQUIRING-EARLY-SETTLEMENT-DECIDEDAn 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.

JSON
{
"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.subscription is the subscription (ACQUIRING-PAYMENT) and data.type the event (ACQUIRING-PAYMENT-CAPTURED): act on data.type. event.id is unique per event.
  • event.accountId is 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's data names it in data.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.id is the payment id, the same id the payment call returned. You need it for refunds. Match the payment to your order with data.externalId.
  • data.userId is the account the sale belongs to, and data.checkoutSessionId the checkout session the payment was made in.
  • data.capturedAt is when the payment was captured, "" before the capture.
  • data.subStatus appears on some failures: see Errors and Decline Codes. data.failureCode is why the payment ended BLOCKED, DECLINED or ERROR, "" on every other event. Match on it rather than on subStatus.
  • data.declineBucket is set when the payment is declined: see decline buckets. "" on every other event.
  • data.savedCardId is the id of the card this payment saved for future charges, or "" when it saved none.
  • data.card is the card's network brand and last4 digits, both "" when unknown (for example on a payment refused before the card was read).
  • data.quote and data.receivables are on ACQUIRING-PAYMENT-CAPTURED only: the quote the sale was opened from, which fixes its rate and every fee (the MDR is inputFee, the main account's markup markupFee), and what each installment is expected to deliver. See the price of a sale.
  • data.beneficiaryWalletId, data.walletAddress and data.walletChain name the wallet the sale is paid to, all "" when it is paid to your account's balance.
EventMeaningWhat to do
ACQUIRING-PAYMENT-CAPTUREDPaid.Fulfil the order.
ACQUIRING-PAYMENT-AUTHORIZEDApproved by the issuer, capture still pending. Usually followed by CAPTURED or CANCELED.Wait for the next event.
ACQUIRING-PAYMENT-DECLINEDRefused 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-BLOCKEDRefused by Avenia before reaching the issuer (failureCode USER_BLOCKED).Offer a new attempt; contact Avenia if unexpected.
ACQUIRING-PAYMENT-ERRORTechnical failure; no money moved. subStatus and failureCode are always INTERNAL_ERROR.Offer a new attempt.
ACQUIRING-PAYMENT-EXPIREDThe customer abandoned the payment or the 3D Secure challenge.Nothing to do.
ACQUIRING-PAYMENT-CANCELEDAuthorization voided before capture; the customer was never charged.Treat as not paid.
ACQUIRING-PAYMENT-REFUNDEDRefunded, in part (status: "PARTIALLY_REFUNDED", with the running refundedAmount) or in full (REFUNDED).Mark as refunded.
ACQUIRING-PAYMENT-VERIFIEDA 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:

FieldMeaning
id, settlementType, status, paymentMethodThe settlement, as in GET /settlements/{settlement-id}.
failureCodeAlways present, and "" on both events. A settlement that ends FAILED sends no event: read the settlement for its failureCode.
grossAmount, netAmountWhat the settlement covers, and what it pays after fees.
payoutCurrency, payoutAmount, walletChainWhat is paid: the currency (BRLA, USDC or USDT), the amount as a decimal string, and the chain.
walletAddress, txHash, paidAtPAID only. Where, the transaction and when. A settlement to a wallet named on the sale carries its walletAddress on every event.
beneficiaryWalletIdThe wallet the settlement pays, "" when it pays your account.
releasedInstallmentsA DEFERRED_RELEASE: the installments it pays, each {paymentId, installmentNumber, releasedAmount}.
releasedReserveA RESERVE_RELEASE: the tranches it gives back, each {origin, settlementId, disputeId, heldAt, releasableAt, releasedAmount}.
receivableOffsetAmount, offsetReceivablesThe debt this settlement netted off, and which debts: each {receivableId, origin, paymentId, receivableOffsetAmount}.
earlySettlementAn 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-OPENED and ACQUIRING-RECEIVABLE-RESOLVED: id, origin (CHARGEBACK, REFUND_AFTER_PAYOUT, ADJUSTMENT or FX_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), openedAt and, on RESOLVED, resolution (RECOVERED, WRITTEN_OFF or REVERSED) and resolvedAt.
  • ACQUIRING-RECEIVABLE-DEBITED: one movement on a debt. receivableId, movementId, movementType, source, direction (DEBIT took from your balance toward the debt, RETURN gave it back: a won dispute reverses a pull), amount (always positive), currency, fxRate, settlementId, outstandingAmount and at. A burn from your account's token balance has movementType SWEEP and source USER_WALLET, with currency the token burned (BRL for BRLA) and fxRate its 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's earlySettlementId, earlySettlementDate, beneficiary, userId (the account whose sales the lines are of), its rates (aveniaMonthlyPct and mainMonthlyPct), its sums (principalAmount, aveniaFee, mainFee, fundedAmount), its lines and settlementId, the settlement that pays a SUB early settlement ("" on a MAIN one). 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 is GET /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​

  1. Verify the signature, and reject anything that fails.
  2. Answer 2xx immediately, within a few seconds, then process asynchronously.
  3. Deduplicate on event.id. The same event can arrive more than once; process it once.
  4. Do not assume order. Within one payment, apply an event only if it moves the payment forward (for example, ignore an AUTHORIZED arriving after CAPTURED).
A delivery that gets a non-2xx response is not resent automatically

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​

GEThttps://api.sandbox.avenia.io:10952/v2/notifications/webhooks/events?subscription=ACQUIRING-PAYMENT&createdAfter=1760000000000
  • subscription takes a subscription, such as ACQUIRING-PAYMENT, not an event: tell the events apart by data.type.
  • createdAfter and createdBefore are Unix time in milliseconds.
  • The response is {"events": [...], "cursor": "..."}: newest first, at most 100 events per page. Pass cursor back 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.