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

Chargeback handling

How chargebacks work

Understand the general chargeback process and key stakeholders involved.

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:

ℹ

️ Secure notifications

Notifications from dLocal are digitally signed. Learn how to verify signatures.

Example notification (POST)

POST: {merchant.chargeback_url}

{
    "id": "CHAR42342",
    "payment_id": "PAY245235",
    "amount": 100.00,
    "currency": "USD",
    "status": "COMPLETED",
    "status_code": 200,
    "status_detail": "The chargeback was executed.",
    "created_date" : "2018-02-15T15:14:52-00:00",
    "notification_url": "http://merchant.com/notifications",
    "order_id": "merchant_num_123456"
} 

Retrieve a chargeback

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

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...' \
    https://api.dlocal.com/chargebacks/CHAR42342

Learn more about retrieving chargebacks.

Dispute resolution

Dispute management flow

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

• 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

Upload dispute documentation

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

Dispute file requirements

The uploaded files should have the following characteristics:

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

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

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

$ 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 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...' \
    https://sandbox.dlocal.com/sandbox-tools/chargebacks

{
    "payment_id" : "PAY4334346343",
    "status" : "PENDING"
}

Learn more about how to simulate chargebacks.