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
{
"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"
}
| Field | Type | Description |
|---|---|---|
id | string | The dispute's ID. |
userId | string | The seller of the disputed payment: your main account or the sub-account that made the sale. |
paymentId | string | The disputed payment. |
disputeType | string | CHARGEBACK, PRE_DISPUTE (an inquiry before a chargeback; it takes nothing) or OTHER. |
isPreDispute | boolean | true for an alert that came before a chargeback. |
status | string | RECEIVED, PENDING_REVIEW, WON, LOST, ACCEPTED or PREVENTED. See Dispute Statuses. |
decision | string | Your decision: CONTEST, ACCEPT, or "" while you have not decided. |
decidedBy | string | The email of the access that contested or accepted, "" until then. |
decidedAt | string | When it was contested or accepted, "" until then. |
reason | string | Why 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 "". |
amount | string | The disputed amount, as a decimal string, written as card acquiring writes amounts (R$ 150.00 reads "150"). |
currency | string | BRL. |
openedAt | string | When the cardholder's bank opened the dispute. |
evidenceDueAt | string | The last moment to upload evidence and contest. |
evidenceSubmittedAt | string | When your evidence was sent to the acquirer. |
contestChannel | string | Once you contest: PROVIDER (submitted right away) or MANUAL (queued and submitted by hand; evidenceSubmittedAt is set once it is). "" before. |
contestDueAt | string | Where an acquirer takes contests by hand, the last day to contest. |
resolvedAt | string | When the dispute reached its outcome. |
collateralReleaseAt | string | For a won dispute, when what the chargeback took is paid back to you from your reserve. |
evidence | array | The files uploaded for the dispute, each a cardDisputeEvidence. |
createdAt | string | When Avenia received the dispute. |
updatedAt | string | When the dispute last changed. |
subAccountId | string | Only 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
| Status | Description |
|---|---|
RECEIVED | Opened; waiting for your decision. |
PENDING_REVIEW | Under review. |
WON | Decided in your favour. |
LOST | Decided against you. |
ACCEPTED | You accepted it. |
PREVENTED | An 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
{
"id": "a6c1e3b7-4d29-4f80-b5a1-2e7d9c0f4b13",
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"sizeBytes": 48211,
"submittedAt": "",
"createdAt": "2026-10-09T09:30:00Z"
}
| Field | Type | Description |
|---|---|---|
id | string | The file's ID. |
fileName | string | The name you gave it. |
contentCategory | string | What it shows. See Upload Evidence. |
sizeBytes | integer | The size of the file, decoded. |
submittedAt | string | When it was sent with a contest, "" until then. |
createdAt | string | When it was uploaded. |
List Disputes
Endpoint
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
subAccountId | string | No | Whose 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. |
paymentId | string | No | Filter by the disputed payment. |
createdAfter | int64 | No | Unix epoch timestamp in milliseconds (UTC). Returns disputes created on or after this instant (createdAt >= createdAfter). |
createdBefore | int64 | No | Unix epoch timestamp in milliseconds (UTC). Returns disputes created strictly before this instant (createdAt < createdBefore). |
cursor | string | No | The 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:
subAccountId | Disputes returned |
|---|---|
| omitted | Your main account's. |
| a sub-account ID | That 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 -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.
{
"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
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dispute-id | string | Yes | The dispute's id, in the path. |
subAccountId | string | No | The 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 -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:
{
"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
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
dispute-id | string | Yes | The dispute's id, in the path. |
subAccountId | string | No | The sub-account the dispute belongs to, omitted for the main account. * is refused. |
X-API-IdempotencyKey header | string | Yes | Names the file: repeating it answers 200 with the file already kept, never a second copy. See Idempotency. |
Request body
{
"fileName": "receipt.pdf",
"contentCategory": "RECEIPT",
"contentBase64": "JVBERi0x..."
}
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | Yes | 3 to 255 characters. |
contentCategory | string | Yes | RECEIPT, PROOF_OF_DELIVERY, PROOF_OF_SERVICE, CUSTOMER_INTERACTION, PAYMENT_DETAIL, REFUND_POLICY, CANCEL_POLICY, SERVICE_AGREEMENT, TERMS_AND_CONDITIONS, PROOF_OF_AUTHENTICITY or OTHERS. |
contentBase64 | string | Yes | The 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 -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:
{
"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
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dispute-id | string | Yes | The dispute's id, in the path. |
subAccountId | string | No | The sub-account the dispute belongs to, omitted for the main account. * is refused. |
There is no body: send none, or {}.
Request example
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
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dispute-id | string | Yes | The dispute's id, in the path. |
subAccountId | string | No | The sub-account the dispute belongs to, omitted for the main account. * is refused. |
Request body
{ "confirmAmount": "150.00" }
| Field | Type | Required | Description |
|---|---|---|---|
confirmAmount | string | Yes | The 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 -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
| Status | Message | When |
|---|---|---|
400 | InvalidFieldError: subAccountId is invalid | subAccountId is neither * nor a UUID, or is * on Upload Evidence, Contest or Accept. |
400 | the X-API-IdempotencyKey header is required on this route | Upload Evidence without the header. |
400 | content is not valid base64, the file is not a PDF, the only type the provider accepts, or a file above the limit | Fix the evidence file. |
400 | confirmAmount is not this dispute's amount: nothing was accepted | Accept a Dispute: send the dispute's amount. |
403 | ForbiddenError | Evidence, 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. |
404 | NotFoundError: subAccountId not found | subAccountId does not belong to your account. |
404 | NotFoundError: dispute not found | There is no dispute with this ID in the account you asked for. A sub-account's dispute read without subAccountId also returns 404. |
409 | this dispute is already resolved or this dispute was already contested or accepted | The dispute can no longer be decided. |
409 | a 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. |
409 | this 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. |
500 | InternalError: please contact us, on a contest | The 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.