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. |
notification_url | String | URL where dlocal will send notifications associated to changes in this chargeback. |
order_id | String | ID of the payment, given by the merchant in their system. |
️ Signature notifications
Chargeback notifications are signed. Learn more.
Example 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
Example request
$ curl \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'X-Version: 2.1' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
https://api.dlocal.com/chargebacks/CHAR42342
See more about how to retrieve a chargeback in the API reference section.
Simulate chargeback (Sandbox only)
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 this method. You can complete the status field with the specific status that you want to test.
Example request
$ curl -X POST \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'Content-Type: application/json' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
https://sandbox.dlocal.com/sandbox-tools/chargebacks
{
"payment_id" : "PAY4334346343",
"status" : "PENDING"
}
See more about how to Simulate chargeback in the API reference section.
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.
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 1 MB in size.
- Dispute should be written in English or the country’s local language.
Example Request
curl -X POST \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'Content-Type: application/json' \
-H 'X-Version: 2.1' \
-H 'User-Agent: MerchantTest / 1.0 ' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
-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 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. |
Updated 6 months ago