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:

PropertyTypeDescription
idStringThe chargeback ID.
payment_idStringThe payment ID.
amountPositive FloatThe amount of the chargeback.
currencyStringThe currency of the chargeback.
statusStringThe status of the chargeback.
status_codeIntegerThe status code of the chargeback.
status_detailStringThe description of the chargeback's status.
created_dateStringThe date of when the chargeback was executed.
notification_urlStringURL where dlocal will send notifications associated to changes in this chargeback.
order_idStringID 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

StatusStatus codeDescription
SUCCESS200Dispute documentation received successfully.
REJECTED300The chargeback is no longer disputable as it is not in PENDING status or due date is expired.
REJECTED301Dispute file is larger than 1MB.
REJECTED302Incorrect file - Not in PDF format, or malformed/corrupted contents.
NOT FOUND404Chargeback not found.