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.

Refunds and Cancellations

One route sends money back to the cardholder: it cancels a payment that was not captured yet and refunds one that was. You do not choose between the two; Avenia decides from the payment's real state.

  • type: "CANCEL": the payment was not captured yet. The authorization is voided and the customer is never charged.
  • type: "REFUND": the payment was captured. The money goes back to the customer's card.

Refunds and dispute decisions require an admin access. If your access is a multi-sig requester, the refund waits for approval.

Cancel or refund a payment​

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/payments/{payment-id}/cancel-or-refund

Parameters​

Path and header

FieldTypeRequiredDescription
{payment-id}stringYesThe id of the payment answer, or event.data.id of a payment webhook.
X-API-IdempotencyKeyheaderYesAny string unique to this refund. Repeating it returns the original result (200) instead of refunding twice.
subAccountIdqueryNoAct for this sub-account.

Body

FieldTypeRequiredDescription
amountdecimalYesThe amount to return in BRL, a JSON number or string with at most 2 decimal places, such as "150.00": the whole payment or part of it. Several partial refunds may follow each other, up to the captured amount; above what is left, 409. A payment authorized and not yet captured can only be cancelled whole: a smaller amount is refused with 400 InvalidFieldError: amount is invalid.
reasonstringYesREQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT or REVERSE. FRAUDULENT feeds the fraud counts the card schemes read.
externalIdstringNoYour own reference for the refund.

Only a payment that is AUTHORIZED, CAPTURED or PARTIALLY_REFUNDED can be reversed. Anything else answers 409 this payment cannot be reversed in its current state.

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/acquiring/payments/e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d/cancel-or-refund" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "X-API-IdempotencyKey: refund-order-10045" \
-d '{
"amount": "150.00",
"reason": "REQUESTED_BY_CUSTOMER",
"externalId": "refund-10045"
}'

Response​

201 (or 200 on a repeat with the same key):

JSON
{
"id": "9a7b4c1e-2d3f-4a5b-8c6d-7e8f9a0b1c2d",
"type": "REFUND",
"paymentStatus": "REFUNDED",
"amount": "150"
}

Each refund is announced with ACQUIRING-PAYMENT-REFUNDED: a partial one with status: "PARTIALLY_REFUNDED" and the running refundedAmount, and the one that completes the amount with status: "REFUNDED". paymentStatus in the response says the same.

Idempotency​

You sendYou get
A new X-API-IdempotencyKeyThe refund, 201.
The same key, same requestThe original result, 200.
The same key, after that refund failed409 the reversal sent with this X-API-IdempotencyKey failed and nothing was sent back; to try again, send it with a new key
The same key, for a different refund of the same payment409 this X-API-IdempotencyKey was already used for a different reversal of this payment; send a new request with a new key
No key400 the X-API-IdempotencyKey header is required on this route

It is safe to repeat a 5xx or a timeout with the same key: you get the existing result, never a second refund.

When a refund does not go through​

You getIt meansWhat to do
500The refund did not go through, or Avenia could not tell whether the acquirer took it (for example, it did not answer in time). Its status in refunds says which: FAILED when nothing was sent back, PENDING when it may or may not have gone out.Read the payment's refunds, or repeat with the same key. On a FAILED refund the repeat answers 409 the reversal sent with this X-API-IdempotencyKey failed and nothing was sent back; to try again, send it with a new key: send a new refund with a new key only if the payment is still reversible. Never send a new key while it is PENDING: if the first one went out, that is a second refund.
200 on a repeat during PENDING, with type ""The refund exists and the acquirer has not said yet whether it was a cancellation or a refund. It does not prove that the money went out.Read the refund in refunds until it is SUCCEEDED or FAILED.

A refund that you or Avenia approved and the acquirer then refused ends FAILED in refunds, with no webhook: read refunds rather than waiting for an event. (A refund that waited for approval and was rejected or expired does announce itself, with ACQUIRING-REFUND-REJECTED.)

What a refund returns of the MDR​

The percentage part of the MDR (in the sale's quote.inputFee) goes back to you in proportion to the refunded amount: a refund of half the sale returns half of that percentage, and the refunds that add up to the whole sale return all of it. The fixed fee pays a service already rendered and, when your account's card pricing says so, it is not returned: it stays with Avenia on every refund, partial or whole, so a refund of the whole sale leaves you owing the fixed fee on top of what you received for it. Whether the fixed fee is kept is a term of your account's card pricing, set by Avenia, and a sale keeps the term in force when it was made; in the sandbox it is kept.

Refunds above your cover wait for approval​

A refund of a payment that was already settled is paid out of what Avenia holds for your account (what you are owed, the buffer and the reserve). When that does not reach the amount, the refund is not refused: it waits for a person at Avenia to approve it. The call answers 202:

JSON
{ "id": "9a7b4c1e-2d3f-4a5b-8c6d-7e8f9a0b1c2d", "amount": "150", "status": "PENDING_APPROVAL", "approvalExpiresAt": "2026-10-28T12:00:00Z" }
  • Nothing is sent to the customer yet. You receive ACQUIRING-REFUND-PENDING-APPROVAL with the same id, plus paymentId, amount, externalId, status and approvalExpiresAt. The refund's state is also in refunds when you read the payment.
  • Approved: the refund goes out as any other and you receive ACQUIRING-PAYMENT-REFUNDED. What your cover did not reach becomes a debt (ACQUIRING-RECEIVABLE-OPENED, which names the refund as refundId), taken from your account's token balance and then from your next settlements: see what a refund or chargeback takes. The 202 does not carry the debt's amount, because your cover moves with your sales and settlements until the decision.
  • Rejected, or not decided by approvalExpiresAt (72 hours by default, set per account): nothing is sent and you receive ACQUIRING-REFUND-REJECTED, with the same id, paymentId, amount, externalId and status, and a failureCode. It never says why a person rejected it: failureCode is then "". The one code it can carry is PAYMENT_NOT_REVERSIBLE, set when the payment stopped being reversible (a chargeback landed) while the refund waited: see refund failure codes.
  • Repeating the call with the same X-API-IdempotencyKey answers 202 with the same refund while it waits. Once rejected, the repeat answers 409 like any failed refund: send a new key.
  • A refund's status, in refunds, is PENDING_APPROVAL, PENDING (sent, outcome not known yet), SUCCEEDED or FAILED. approvalExpiresAt is set only while it waits, and failureCode only on a FAILED refund whose cause you can act on ("" otherwise).

This 202 is not the multi-sig one below: it carries status: "PENDING_APPROVAL" and the refund's id, never an operationId.

Testing approval in the sandbox​

In the sandbox you play the person who decides, with the id the 202 returned:

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/refunds/{refund-id}/simulate-decision
JSON
{ "decision": "APPROVED" }

decision is APPROVED or REJECTED. It answers 200:

JSON
{
"refundId": "9a7b4c1e-2d3f-4a5b-8c6d-7e8f9a0b1c2d",
"decision": "APPROVED",
"refundStatus": "SUCCEEDED",
"coverAmount": "90",
"shortfallAmount": "60"
}

refundStatus says where the refund ended: SUCCEEDED when it went out, or NOT_SENT when you approved it and it did not go out. With REJECTED the refund becomes FAILED, and coverAmount and shortfallAmount are "0". Errors: 400 when decision is not APPROVED or REJECTED; 404 when the refund is not waiting for approval (or is not yours); 409 when the request already expired, when the payment no longer has that much left to refund, or when it can no longer be refunded (a chargeback landed): in these cases the refund is closed and nothing is sent.

shortfallAmount is the debt planned at the decision; the debt itself is announced by the notice. The events above follow within about a minute. To get a refund above your cover, settle a payment and refund it in full. Outside the sandbox the route answers 404 simulating a refund decision exists only in the sandbox; here a person decides. It requires an admin access, like the refund.

What a refund or chargeback takes, and in what order​

When a refund of a settled payment, or a chargeback, takes a sale back, the sub-account the sale was made for and the main account each owe back their share of it. Each share is taken at once, in this order, and each step gives what it has before the next takes the rest:

The sub-account's share

  1. Its collateral: the rolling reserve (the sale's own first, then the rest, nearest to release first), or the workspace's buffer, whichever the account's collateral is. What the buffer pays, the sub-account then owes the main account, taken from its next settlements before it is paid.
  2. What it is owed now and not on its way out yet (payableAmount in the balance).
  3. Its account's token balance at Avenia: its BRLA, USDC and USDT are burned: the sale's payout token first, valued at the price read when the refund or chargeback arrived, then BRLA at 1 BRL each, then the other USD stablecoin at the price when it is burned. A sale paid out in BRLA burns BRLA, then USDC, then USDT. Other tokens are never burned. A beneficiary wallet is never reached.
  4. What is still left stays a debt, netted off its next settlements.

The main account's share (its markups on the sale): its markups due on that sub-account and not paid out yet (on the sale, then on the conversion), then the workspace's buffer, then the main account's token balance (burned in the same token order), and what is left stays a debt, paid from its next markups.

Each step that pays the sub-account's debt arrives as ACQUIRING-RECEIVABLE-DEBITED. A burn has movementType SWEEP and source USER_WALLET: amount is what the debt came down by, in BRL, currency the token burned (BRL for BRLA) and fxRate the BRL price of one unit it was valued at, so the units burned are amount ÷ fxRate. The burns run shortly after the refund or chargeback is booked. The main account's share sends no debt events.

A chargeback you win gives every step back: what was burned is minted back, the same units of the same token, to the balance it was burned from, and the rest returns as described in Disputes.

FX difference on sales paid out in USDC or USDT​

A sale paid out in USDC or USDT was converted at the rate its capture locked. When it is refunded or charged back, Avenia buys that currency back at the price of the day. If the price rose between the locked rate and the price read when the refund or chargeback arrived, the difference is charged as its own debt:

FX difference = base × (price today ÷ locked rate − 1), rounded to the cent

base is the sub-account's share of what was taken back that had already been paid out to it, in BRL. Nothing is charged when the price fell or stayed the same, nor on a sale paid out in BRLA. The chargeback fee and any amount above the sale are not adjusted.

Example. A sale converted at a locked rate of 5.00 BRL per USDC. A refund takes back R$1,000.00 of the share already paid out to you.

Price when the refund arrivesFX difference
5.251,000.00 × (5.25 ÷ 5.00 − 1) = R$50.00
4.90Nothing: the price fell.

The FX difference is a debt with origin FX_DIFFERENCE, announced by ACQUIRING-RECEIVABLE-OPENED with the payment's paymentId and the refundId or disputeId of what took the sale back. It is taken at once in the order above, and what nothing reaches stays owed. The main account is charged the same way on its markups taken back, with no event. A chargeback you win reverses both: what they took comes back and the debt ends REVERSED.

With multi-approval (multi-sig)​

If the access that calls is a multi-sig requester, the refund (operation type ACQUIRING_CANCEL_OR_REFUND_PAYMENT) is not made right away. The call answers 202:

JSON
{ "operationId": "5d0c8e41-7a2b-4f93-b6e1-3c9a0d2f8b75", "status": "PENDING" }

The approval that reaches the quorum executes the refund by itself, on behalf of the requester. The requester does not call /execute: calling it after the refund went out answers 409 operation is not approved or is already executed.

Never answer that 409 with a new refund

Do not send the refund again with a new X-API-IdempotencyKey: that is a second refund. After the approvals, read the result instead: the operation (GET /v2/account/multi-sig-operations/{operationId}) and the refund in refunds when you read the payment, and wait for ACQUIRING-PAYMENT-REFUNDED.

The one case that needs /execute is an operation that stays APPROVED because the execution was refused before it ran (for example, the requester lost its permission); once the cause is fixed, the requester can run it. See multi-approval operations. Accepting a dispute works the same way (ACQUIRING_ACCEPT_DISPUTE).

Refunds Avenia makes​

Some fraud checks run after the capture. When one of them fails, Avenia refunds the payment to the card on its own and you receive ACQUIRING-PAYMENT-REFUNDED without having asked for a refund. Handle it as any refund: stop or undo the fulfilment if you still can.