---
updatedAt: 2026-07-27T09:12:27.000Z
agentTools:
  projectIndex: https://docs.dlocal.com/llms.txt
---

# Chargebacks

Learn how to handle chargebacks, address disputes, and test integrations effectively.

**A chargeback occurs when a cardholder disputes a charge with their issuing bank**. When this happens, dLocal notifies your application asynchronously through a webhook.

Below, you'll find detailed information on how to manage chargebacks using dLocal’s API, including notification handling, dispute documentation uploads, and testing with our sandbox environment.

# Overview

[block:html]
{
  "html": "\n<style>\n  \n  .main {\n    margin-top: -25px;\n    margin-left: auto;\n    margin-right: auto;\n    margin-bottom: 5px;\n    display: grid;\n    grid-template-columns: repeat(3, 1fr); /* Tres columnas */\n    width: 740px; /* Ancho máximo de la caja */\n}\n\n.overview-card1 {\n    position: relative; /* Asegúrate de que el contenedor sea relativo para posicionar el pseudoelemento */\n    width: 100%;\n    max-width: 233px;\n    box-sizing: border-box;\n    margin: 0;\n}\n\n.overview-card1::after {\n    content: '';\n    position: absolute;\n    right: 0; /* Pega la línea al borde derecho */\n    top: 30%; /* Ajusta la posición superior de la línea */\n    height: 70%; /* Establece el alto de la línea al 60% */\n    width: 1px; /* Grosor de la línea */\n    background-color: #D2D8EC; /* Color de la línea */\n}\n  \n.overview-card2 {\n    position: relative; /* Asegúrate de que el contenedor sea relativo para posicionar el pseudoelemento */\n    width: 100%;\n    max-width: 233px;\n    box-sizing: border-box;\n    margin: 0;\n}\n\n.overview-card-upper-side1 {\n    height: 105px;\n    padding: 20px;\n    background-color: transparent;\n    text-align: left;\n}\n\n.overview-card-bottom-side {\n    position: relative;\n    width: 100%;\n    height: 100%;\n    padding: 30px;\n    padding-right: 20px;\n    background-color: transparent;\n    border-radius: 16px;\n}\n\n.overview-card-title1 {\n    font-family: 'Plus Jakarta Sans', sans-serif;\n    font-size: 24px;\n    font-weight: 700;\n    line-height: 26.4px;\n}\n\n.overview-card-content1 {\n    font-size: 14px;\n    font-weight: 300;\n    margin-top: 20px;\n    line-height: 20px;\n    margin-bottom: 40px!important;\n}\n\n.overview-icon1 {\n    margin-bottom: -5px;\n    margin-top: 20px;\n}\n  \n.doc-link {\n        position: relative;\n        font-weight: 500;\n        color: #21A35B !important;\n        text-decoration: none;\n        display: block;\n    }\n  \n\ndiv:not(.markdown-body) .doc-link:hover {\n            text-decoration: none;\n            color: #1043FA !important;\n            transform: translateX(0.2em);\n        }\n\n.overview-card-title1:hover {\n    color: #2D59F5 !important;\n    cursor:pointer;\n    transform: none!important;\n}\n\n    div:not(.markdown-body) .doc-link_arrow {\n        display: inline-block;\n        height: 1em;\n        width: auto;\n        vertical-align: middle;\n        margin-left: 0.2em;\n        margin-top: -0.1em;\n    }\n  \n     div:not(.markdown-body) .doc-link:hover .doc-link_arrow-color {\n            fill: #1043FA !important;\n        }\n\n      [data-color-mode=\"dark\"] .overview-icon1 img {\n        filter: brightness(0) invert(1);\n        transition: filter 0.3s ease;\n\t\t\t\t\t\t}\n  \n/* Media Queries para dispositivos móviles */\n@media (max-width: 768px) {\n  .main {\n    grid-template-columns: repeat(2, 1fr); /* Dos columnas en pantallas medianas */\n  }\n}\n\n@media (max-width: 480px) {\n  .main {\n    grid-template-columns: 1fr; /* Una columna en pantallas pequeñas */\n}\n</style>\n  \n    <div class=\"main\">\n\n     <!-- Handle -->\n      <div class=\"overview-card1\">\n     <div class=\"overview-card-bottom-side\">\n           <h3 class=\"overview-card-title1\">Chargeback handling</h3>\n          <p class=\"overview-card-content1\">\n            Manage incoming chargebacks effectively.  \n        </p>\n          <a href=\"#how-chargebacks-work\" class=\"doc-link\">How chargebacks work</a>\n          <a href=\"#chargeback-notifications\" class=\"doc-link\">Chargeback notifications</a>\n          <a href=\"#retrieve-a-chargeback\" class=\"doc-link\">Retrieve a chargeback</a>\n        </div>\n      </div>\n      \n      <!-- Dispute -->\n      <div\n        class=\"overview-card1\">\n        <div class=\"overview-card-bottom-side\">\n           <h3 class=\"overview-card-title1\">Dispute <br>resolution</h3>\n          <p class=\"overview-card-content1\">\n           Provide documentation to contest chargebacks.   \n          </p>\n          <a href=\"#dispute-management-flow\" class=\"doc-link\">Dispute management flow</a>\n          <a href=\"#upload-dispute-documentation\" class=\"doc-link\">Upload documentation</a>\n          <a href=\"#dispute-file-requirements\" class=\"doc-link\">Dispute file requirements</a>\n        </div>\n      </div>  \n      \n      <!-- Testing -->\n      <div class=\"overview-card2\" onclick=\"parent.location='/docs/morocco#alternative-payment-method'\">\n    <div class=\"overview-card-bottom-side\">\n           <h3 class=\"overview-card-title1\">Testing & simulation</h3>\n          <p class=\"overview-card-content1\">\n             Validate your integration using a sandbox.  \n        </p>\n          <a href=\"#simulate-a-chargeback-sandbox-only\" class=\"doc-link\">Testing chargebacks</a>\n        </div>\n      </div> \n      \n    </div>"
}
[/block]

<br />

***

# Chargeback handling

## How chargebacks work

Understand the general chargeback process and key stakeholders involved.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/fe997eb7657492a2905f94c8b40fa13895d417dda67e16427ed493acf586358a-Payins.chargebacks_-_general.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

## Chargeback notifications

When a cardholder initiates a chargeback, dLocal will send an asynchronous notification (POST request) to the registered merchant chargeback notification URL with the following parameters:

| Property             | Type           | Description                                                                                                                 |
| -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | String         | The chargeback ID.                                                                                                          |
| `payment_id`         | String         | The payment ID.                                                                                                             |
| `created_date`       | String         | The date of when the chargeback was executed.                                                                               |
| `currency`           | String         | The currency of the chargeback.                                                                                             |
| `amount`             | Positive Float | The amount of the chargeback.                                                                                               |
| `status`             | String         | Current [status](https://docs.dlocal.com/reference/chargeback-status)  of the chargeback.                                                                 |
| `status_code`        | Integer        | The status code of the chargeback.                                                                                          |
| `status_detail`      | String         | The description of the chargeback's status.                                                                                 |
| `notification_url`   | String         | URL where dLocal will send chargeback notifications and subsequent updates.                                                 |
| `order_id`           | String         | ID given by the merchant in their system.                                                                                   |
| `chargeback_date`    | String         | ISO 8601 timestamp indicating when the chargeback event was recorded by the acquirer/processor.                             |
| `chargeback_stage`   | String         | Current stage of the chargeback process as reported by the acquirer/scheme.                                                 |
| `processor_id`       | String         | Identifier of the processor/acquirer that originated or reported the chargeback (when available).                           |
| `reason_code`        | String         | Numeric or alphanumeric code specifying the reason for the chargeback.                                                      |
| `reason_description` | String         | Description of the reason associated with the `reason_code`.                                                                |
| `arn`                | String         | Acquirer Reference Number. A 23-digit identifier assigned by the acquirer to track the transaction across the card network. |

> ℹ ️ Secure notifications
>
> Notifications from dLocal are digitally signed. [Learn how to verify signatures](https://docs.dlocal.com/docs/receive-notifications#signature-of-notifications).

<br />

### Example notification (POST)

POST: *{merchant.chargeback_url}*

```json Example request
{
  "id": "CHAR42342",
  "payment_id": "PAY245235",
  "created_date": "2025-10-21T17:38:57.000+0000",
  "currency": "UYU",
  "amount": 1000,
  "status": "PENDING",
  "status_code": 100,
  "status_detail": "The chargeback is pending.",
  "notification_url": "http://merchant.com/notifications",
  "order_id": "1122334455667788",
  "chargeback_date": "2025-10-21T17:38:57.000+0000",
  "chargeback_stage": "OTHER",
  "processor_id": "156",
  "reason_code": "10.4",
  "reason_description": "Other Fraud: Card-absent Environment/Condition.",
  "arn": "74049384186711978854903"
}
```

## Retrieve a chargeback

Fetch detailed information about a chargeback using the dLocal API endpoint.

### Example request

Send a `GET` request to `https://api.dlocal.com/chargebacks/{chargeback_id}`.

```json Example request
$ curl \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: {x-login}' \
   -H 'X-Trans-Key: {x-trans-key}' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...'
```

[Learn more about retrieving chargebacks.](https://docs.dlocal.com/reference/retrieve-a-chargeback)

***

# Dispute resolution

## Dispute management flow

The following diagram shows the different statuses a chargeback may go through, along with their transitions:

* `INQUIRY` : The issuer has requested additional information about the transaction. No funds movement occurs yet. If you receive an INQUIRY status, respond with supporting documentation before the case progresses to `PENDING` or `COMPLETED`.
* `PENDING`: Initial status after receiving a chargeback.
* If you **do not dispute the chargeback before the deadline**:
  * It becomes `COMPLETED`.
  * Funds are permanently debited from your balance.
* If you **dispute the chargeback before the deadline**:
  * It moves to `DISPUTE_RECEIVED` and after that will change to `IN_DISPUTE` once the deadline passes.
  * Funds are temporarily debited from your balance during the dispute.
* **After the dispute**:
  * If the **issuer rules in favor of the merchant**: Status changes to `REVERSAL`, and the funds are credited back to your balance as a credit note.
  * If the **issuer rules in favor of the cardholder**: Status becomes `DISPUTE_LOST`, and funds remain permanently debited from your balance.

### Chargeback status transitions

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/8c20ed1659d73f51308bc286377c657b1d6fb385e70195b6ea5c3ff7ec11d1ad-Payins-chargeback_flow.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

## Upload dispute documentation

When disputing chargebacks, merchants must provide supporting documentation. dLocal will forward this evidence to the issuer bank for evaluation.

> The Dispute API is available for merchants in all markets supported by dLocal.

## Dispute file requirements

The uploaded files should have the following characteristics:

* [x] **Single PDF** file per chargeback dispute.
* [x] File must be **base64-encoded** within the POST request body.
* [x] File size limit: **1Mb**.
* [x] Document language: **English or the local language** of the transaction country.

### Example request

```json Example request
curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: {x-login}' \
   -H 'X-Trans-Key: {x-trans-key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...' \
   -d '{body}'
https://api.dlocal.com/chargebacks/dispute/CBK-12345-1512742-823b91f0-3b47-47f0-915c-f15d98d1a20b


//body:
{
    "filename": "chargeback_dispute.pdf",
    "content": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjMgMCBvYmoKPDwgL0ZpbHRlc ..."
}
```

### Response codes

| Status      | Status code | Description                                                                                                  |
| :---------- | :---------- | :----------------------------------------------------------------------------------------------------------- |
| `SUCCESS`   | 200         | Dispute documentation received successfully.                                                                 |
| `REJECTED`  | 300         | The chargeback is no longer disputable as it is not in `PENDING` or `INQUIRY` status or due date is expired. |
| `REJECTED`  | 301         | Dispute file is larger than 1MB.                                                                             |
| `REJECTED`  | 302         | Incorrect file - Not in PDF format, or malformed/corrupted contents.                                         |
| `NOT FOUND` | 404         | Chargeback not found.                                                                                        |

***

# Testing & simulation

## Simulate a chargeback (Sandbox only)

In production, chargebacks are initiated by the cardholder directly through their bank.

In the dLocal Sandbox environment, chargebacks can be simulated for testing purposes. To simulate a chargeback, submit a request specifying the desired `status`.

### Example request

Send a `POST` request to `https://sandbox.dlocal.com/sandbox-tools/chargebacks`.

```json Example request
{
    "payment_id" : "PAY4334346343",
    "status" : "PENDING"
}
```

[Learn more about how to simulate chargebacks.](https://docs.dlocal.com/reference/simulate-chargeback-sandbox-only)