Chargebacks

Chargeback asynchronous notification

If a chargeback was applied (requested by the user) a notification is sent to the previously registered Merchant chargeback notification URL by POST protocol, sending the following parameters:
Property
Type
Description
id
String
The chargeback id.
payment_id
String
The payment id.
amount
Positive Float
The amount of the chargeback.
currency
String
The currency of the chargeback.
status
String
The status of the chargeback.
status_code
Integer
The status code of the chargeback.
status_detail
String
The description of the chargeback's status.
created_date
String
The date of when the chargeback was executed.
Chargeback notifications are signed. Learn more about the signature notifications here.
Example post
POST: {merchant.chargeback_url}
1
{
2
"id": "CHAR42342",
3
"payment_id": "PAY245235",
4
"amount": 100.00,
5
"currency": "USD",
6
"status": "COMPLETED",
7
"status_code": "200",
8
"status_detail": "The chargeback was executed.",
9
"created_date" : "2018-02-15T15:14:52-00:00"
10
"order_id": "merchant_num_123456"
11
}
Copied!
get
https://api.dlocal.com/chargebacks/
{chargeback_id}
Retrieve a Chargeback

Example Request

1
$ curl \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
7
https://api.dlocal.com/chargebacks/CHAR42342
Copied!
get
https://api.dlocal.com/chargebacks/
{chargeback_id}/status
Retrieve a Chargeback Status

Chargeback status

Status
Status code
Description
PENDING
100
The chargeback is pending.
DISPUTE_RECEIVED
101
Dispute documentation received
COMPLETED
200
The chargeback was executed.
IN_DISPUTE
201
Dispute documentation was sent to the acquirer.
DISPUTE_LOST
202
The chargeback dispute was lost.
REVERSAL
700
The chargeback dispute was won.
INQUIRY
800
Request for information received.
In the Production environment, Chargebacks are triggered by the buyer by calling their bank.
In dLocal's Sandbox environment though, merchants can simulate a Chargeback using the method described below. You can complete the status field with the specific status that you want to test.
post
https://sandbox.dlocal.com
/sandbox-tools/chargebacks
Simulate Chargeback (Sandbox only)

Example Request

1
$ curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'Content-Type: application/json' \
6
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
7
https://sandbox.dlocal.com/sandbox-tools/chargebacks
Copied!

Example Request Body

1
{
2
"payment_id" : "PAY4334346343",
3
"status" : "PENDING"
4
}
Copied!

Upload dispute documentation

The Chargebacks API allows dLocal clients to upload dispute documentation to pending chargebacks received, so that dLocal can submit these documents to the relevant issuers for processing.
post
https://api.dlocal.com/chargebacks
/dispute/{chargeback_id}
Upload dispute documentation

Dispute file requirements

The uploaded files should have the following characteristics:
  • Each chargeback dispute must be fully contained within a single file.
  • File must be in PDF format, encoded as base64 within the dispute POST request.
  • File must be no larger than 1Mb in size.
  • Dispute should be written in English or the country’s local language.

Example Request

1
curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'Content-Type: application/json' \
6
-H 'X-Version: 2.1' \
7
-H 'User-Agent: MerchantTest / 1.0 ' \
8
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
-d '{body}'
10
https://api.dlocal.com/chargebacks/dispute/CBK-12345-1512742-823b91f0-3b47-47f0-915c-f15d98d1a20b
11
12
13
//body:
14
{
15
"filename": "chargeback_dispute.pdf",
16
"content": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjMgMCBvYmoKPDwgL0ZpbHRlc ..."
17
}
Copied!

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.