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 Disputes (Chargebacks)

A card dispute is a cardholder contesting a card payment with their bank: a chargeback, or a pre-dispute inquiry that comes before one. Avenia records it as a cardDispute, linked to the payment, and notifies you with the DISPUTE webhook. You either contest it with evidence or accept it.

How a chargeback takes money from your settlements, and what a won dispute gives back, is in the Card Acquiring guide: Disputes (Chargebacks).

Reading disputes works with any access. Evidence, contest and accept require an admin access, and accepting also goes through multi-sig when your access uses it.

The cardDispute Object​

JSON
{
"id": "3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68",
"userId": "99b76c8d-8ab8-4c91-bb7a-aaf619874e23",
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"disputeType": "CHARGEBACK",
"isPreDispute": false,
"status": "RECEIVED",
"decision": "",
"decidedBy": "",
"decidedAt": "",
"reason": "REQUESTED_BY_CUSTOMER",
"amount": "150",
"currency": "BRL",
"openedAt": "2026-10-08T15:10:00Z",
"evidenceDueAt": "2026-10-20T00:00:00Z",
"evidenceSubmittedAt": "",
"contestChannel": "",
"contestDueAt": "",
"resolvedAt": "",
"collateralReleaseAt": "",
"evidence": [],
"createdAt": "2026-10-08T15:10:01Z",
"updatedAt": "2026-10-08T15:10:01Z"
}
FieldTypeDescription
idstringThe dispute's ID.
userIdstringThe seller of the disputed payment: your main account or the sub-account that made the sale.
paymentIdstringThe disputed payment.
disputeTypestringCHARGEBACK, PRE_DISPUTE (an inquiry before a chargeback; it takes nothing) or OTHER.
isPreDisputebooleantrue for an alert that came before a chargeback.
statusstringRECEIVED, PENDING_REVIEW, WON, LOST, ACCEPTED or PREVENTED. See Dispute Statuses.
decisionstringYour decision: CONTEST, ACCEPT, or "" while you have not decided.
decidedBystringThe email of the access that contested or accepted, "" until then.
decidedAtstringWhen it was contested or accepted, "" until then.
reasonstringWhy the cardholder disputed, exactly as it was reported (for example REQUESTED_BY_CUSTOMER): free text, not a fixed list of values. The first report of the dispute that carries a reason sets it, and it doesn't change after; until then it is "".
amountstringThe disputed amount, as a decimal string, written as card acquiring writes amounts (R$ 150.00 reads "150").
currencystringBRL.
openedAtstringWhen the cardholder's bank opened the dispute.
evidenceDueAtstringThe last moment to upload evidence and contest.
evidenceSubmittedAtstringWhen your evidence was sent to the acquirer.
contestChannelstringOnce you contest: PROVIDER (submitted right away) or MANUAL (queued and submitted by hand; evidenceSubmittedAt is set once it is). "" before.
contestDueAtstringWhere an acquirer takes contests by hand, the last day to contest.
resolvedAtstringWhen the dispute reached its outcome.
collateralReleaseAtstringFor a won dispute, when what the chargeback took is paid back to you from your reserve.
evidencearrayThe files uploaded for the dispute, each a cardDisputeEvidence.
createdAtstringWhen Avenia received the dispute.
updatedAtstringWhen the dispute last changed.
subAccountIdstringOnly in answers to subAccountId=*: the sub-account the dispute belongs to, or "" for the main account. Absent when the dispute belongs to a hidden sub-account or your fee account, or when its owner can't be resolved. See Main account, sub-account or whole account.

Every instant is RFC 3339 in UTC, and "" where there is none yet.

Dispute Statuses​

StatusDescription
RECEIVEDOpened; waiting for your decision.
PENDING_REVIEWUnder review.
WONDecided in your favour.
LOSTDecided against you.
ACCEPTEDYou accepted it.
PREVENTEDAn alert that stopped the chargeback before it landed.

An outcome (WON, LOST, ACCEPTED, PREVENTED) is final for that dispute. Each status sends its own webhook.

The cardDisputeEvidence Object​

JSON
{
"id": "a6c1e3b7-4d29-4f80-b5a1-2e7d9c0f4b13",
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"sizeBytes": 48211,
"submittedAt": "",
"createdAt": "2026-10-09T09:30:00Z"
}
FieldTypeDescription
idstringThe file's ID.
fileNamestringThe name you gave it.
contentCategorystringWhat it shows. See Upload Evidence.
sizeBytesintegerThe size of the file, decoded.
submittedAtstringWhen it was sent with a contest, "" until then.
createdAtstringWhen it was uploaded.

List Disputes​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/disputes/card

Query Parameters​

ParameterTypeRequiredDescription
subAccountIdstringNoWhose disputes to list: omit it for your main account, send a sub-account ID for that sub-account, or * for your whole account. See the table below.
paymentIdstringNoFilter by the disputed payment.
createdAfterint64NoUnix epoch timestamp in milliseconds (UTC). Returns disputes created on or after this instant (createdAt >= createdAfter).
createdBeforeint64NoUnix epoch timestamp in milliseconds (UTC). Returns disputes created strictly before this instant (createdAt < createdBefore).
cursorstringNoThe cursor of the previous page, to fetch the next one.

A createdAfter or createdBefore that is not a number is ignored.

The filters apply within the account subAccountId selects. To find the dispute of a sub-account's payment, send that sub-account's ID or *.

Main account, sub-account or whole account​

subAccountId works as on PIX disputes:

subAccountIdDisputes returned
omittedYour main account's.
a sub-account IDThat sub-account's. 403 if the sub-account is in this access's subaccount blacklist, 404 if it isn't one of your sub-accounts.
*Your whole account's: the main account and every sub-account. Each dispute also carries subAccountId, the sub-account it belongs to, or "" for the main account; it is absent for a hidden sub-account's or your fee account's dispute, or when the owner can't be resolved. An access with a subaccount blacklist gets 403.

* works on the two reads only. Upload Evidence, Contest and Accept act on one account's dispute: send the sub-account's ID, or none for the main account. * there answers 400 InvalidFieldError: subAccountId is invalid.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/disputes/card?createdAfter=1793491200000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

The disputes come newest first, 50 per page. When the response cursor is non-empty, pass it back as the cursor query parameter to fetch the next page. An empty cursor means there are no more pages.

JSON
{
"cardDisputes": [
{
"id": "3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68",
"userId": "99b76c8d-8ab8-4c91-bb7a-aaf619874e23",
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"disputeType": "CHARGEBACK",
"isPreDispute": false,
"status": "RECEIVED",
"decision": "",
"decidedBy": "",
"decidedAt": "",
"reason": "REQUESTED_BY_CUSTOMER",
"amount": "150",
"currency": "BRL",
"openedAt": "2026-10-08T15:10:00Z",
"evidenceDueAt": "2026-10-20T00:00:00Z",
"evidenceSubmittedAt": "",
"contestChannel": "",
"contestDueAt": "",
"resolvedAt": "",
"collateralReleaseAt": "",
"evidence": [],
"createdAt": "2026-10-08T15:10:01Z",
"updatedAt": "2026-10-08T15:10:01Z"
}
],
"cursor": ""
}

Get a Dispute by ID​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/disputes/card/{dispute-id}

Parameters​

ParameterTypeRequiredDescription
dispute-idstringYesThe dispute's id, in the path.
subAccountIdstringNoThe account the dispute belongs to, as in List Disputes. A sub-account's dispute read without it returns 404. With *, any dispute of your account is found, and the answer carries its subAccountId as in List Disputes.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/disputes/card/3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

The dispute, wrapped in a cardDispute object, in the format above:

JSON
{
"cardDispute": {
"id": "3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68",
"userId": "99b76c8d-8ab8-4c91-bb7a-aaf619874e23",
"paymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"disputeType": "CHARGEBACK",
"isPreDispute": false,
"status": "RECEIVED",
"decision": "",
"decidedBy": "",
"decidedAt": "",
"reason": "REQUESTED_BY_CUSTOMER",
"amount": "150",
"currency": "BRL",
"openedAt": "2026-10-08T15:10:00Z",
"evidenceDueAt": "2026-10-20T00:00:00Z",
"evidenceSubmittedAt": "",
"contestChannel": "",
"contestDueAt": "",
"resolvedAt": "",
"collateralReleaseAt": "",
"evidence": [
{
"id": "a6c1e3b7-4d29-4f80-b5a1-2e7d9c0f4b13",
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"sizeBytes": 48211,
"submittedAt": "",
"createdAt": "2026-10-09T09:30:00Z"
}
],
"createdAt": "2026-10-08T15:10:01Z",
"updatedAt": "2026-10-09T09:30:00Z"
}
}

Upload Evidence​

Before contesting, upload one or more PDFs, one per call. Evidence is accepted only while the dispute is open (RECEIVED or PENDING_REVIEW).

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/disputes/card/{dispute-id}/evidence

Parameters​

FieldTypeRequiredDescription
dispute-idstringYesThe dispute's id, in the path.
subAccountIdstringNoThe sub-account the dispute belongs to, omitted for the main account. * is refused.
X-API-IdempotencyKey headerstringYesNames the file: repeating it answers 200 with the file already kept, never a second copy. See Idempotency.

Request body​

JSON
{
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"contentBase64": "JVBERi0x..."
}
FieldTypeRequiredDescription
fileNamestringYes3 to 255 characters.
contentCategorystringYesRECEIPT, PROOF_OF_DELIVERY, PROOF_OF_SERVICE, CUSTOMER_INTERACTION, PAYMENT_DETAIL, REFUND_POLICY, CANCEL_POLICY, SERVICE_AGREEMENT, TERMS_AND_CONDITIONS, PROOF_OF_AUTHENTICITY or OTHERS.
contentBase64stringYesThe file, base64 encoded. It must be a PDF of at most 768 KB (786,432 bytes) once decoded. The body of this one route may reach about 1.1 MB, an exception to the card acquiring 4 KB rule.

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/disputes/card/3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68/evidence" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-H "X-API-IdempotencyKey: evidence-receipt-10045" \
-d '{
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"contentBase64": "JVBERi0x..."
}'

Response​

201 for a new file, 200 for a repeat of the same X-API-IdempotencyKey, with the file wrapped in a cardDisputeEvidence object:

JSON
{
"cardDisputeEvidence": {
"id": "a6c1e3b7-4d29-4f80-b5a1-2e7d9c0f4b13",
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"sizeBytes": 48211,
"submittedAt": "",
"createdAt": "2026-10-09T09:30:00Z"
}
}

Contest a Dispute​

Sends every file uploaded for the dispute to the acquirer.

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/disputes/card/{dispute-id}/contest

Parameters​

ParameterTypeRequiredDescription
dispute-idstringYesThe dispute's id, in the path.
subAccountIdstringNoThe sub-account the dispute belongs to, omitted for the main account. * is refused.

There is no body: send none, or {}.

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/disputes/card/3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68/contest" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

200 with the dispute wrapped in a cardDispute object, as in Get a Dispute by ID, now with decision CONTEST, decidedBy, decidedAt and contestChannel.

With no evidence uploaded, it answers 409 upload at least one evidence before contesting; after the evidence deadline, 409 the deadline to contest this dispute has passed.

Accept a Dispute​

Accepting cannot be undone.

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/account/disputes/card/{dispute-id}/accept

Parameters​

ParameterTypeRequiredDescription
dispute-idstringYesThe dispute's id, in the path.
subAccountIdstringNoThe sub-account the dispute belongs to, omitted for the main account. * is refused.

Request body​

JSON
{ "confirmAmount": "150.00" }
FieldTypeRequiredDescription
confirmAmountstringYesThe dispute's amount, to confirm what you accept. Any other value answers 400 confirmAmount is not this dispute's amount: nothing was accepted.

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/disputes/card/3d8f5a10-6b2c-4e97-a1d4-9c0e7b5f2a68/accept" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "confirmAmount": "150.00" }'

Response​

200 with the dispute wrapped in a cardDispute object, as in Get a Dispute by ID, now ACCEPTED, with decision ACCEPT, decidedBy and decidedAt.

With multi-sig it answers 202 with an operationId, as a refund does.

Errors​

StatusMessageWhen
400InvalidFieldError: subAccountId is invalidsubAccountId is neither * nor a UUID, or is * on Upload Evidence, Contest or Accept.
400the X-API-IdempotencyKey header is required on this routeUpload Evidence without the header.
400content is not valid base64, the file is not a PDF, the only type the provider accepts, or a file above the limitFix the evidence file.
400confirmAmount is not this dispute's amount: nothing was acceptedAccept a Dispute: send the dispute's amount.
403ForbiddenErrorEvidence, contest or accept from an access that is not admin; subAccountId=* from an access with a subaccount blacklist; or subAccountId is in this access's blacklist.
404NotFoundError: subAccountId not foundsubAccountId does not belong to your account.
404NotFoundError: dispute not foundThere is no dispute with this ID in the account you asked for. A sub-account's dispute read without subAccountId also returns 404.
409this dispute is already resolved or this dispute was already contested or acceptedThe dispute can no longer be decided.
409a previous submission of this dispute has no known outcome yet; ...A decision may already have been taken: wait for the dispute's status to change before deciding again.
409this dispute's acquirer does not take a contest; ... or no contest term covers this dispute's acquirer and brand, so it has no deadline and cannot be contested yet; ...Nothing was decided. Contact Avenia.
500InternalError: please contact us, on a contestThe submission did not go through, or it is not known whether it did; the answer does not say which. Read the dispute before contesting again: a repeat answers 409 a previous submission of this dispute has no known outcome yet while a submission may have been taken. If it persists, contact Avenia with the dispute ID.

Webhook​

Register your webhook with the DISPUTE subscription, or *, to receive CARD-DISPUTE-<STATUS> each time a dispute reaches a status: CARD-DISPUTE-RECEIVED, -PENDING_REVIEW, -WON, -LOST, -ACCEPTED and -PREVENTED. Each event carries the dispute in data.cardDispute, in the format above. A won or prevented dispute is first RECEIVED, so it sends CARD-DISPUTE-RECEIVED and then CARD-DISPUTE-WON or -PREVENTED; one whose first notice is already LOST sends only CARD-DISPUTE-LOST. A win is announced only by CARD-DISPUTE-WON. The payload is in Webhook Events, and how to register a webhook in Webhook Management.

Simulating a chargeback in the sandbox​

Create a payment whose externalId is one of the values in Sandbox: Test Cards and Scenarios, with the approved test card. A couple of minutes later the test acquirer opens a chargeback on it, and the dispute arrives as it would in production.