This service allows you to create and read refunds of an existing payment.
For card payments, a Refund is the reversal of a credit card payment, where the funds are taken from the Merchant and given back to the Card Holder. For alternative payment methods, a bank transfer will be made to the customer. A refund processing fee may apply.
currency
is present.amount
is present.type
of the payment is TICKET
or BANK_TRANSFER
.type
of the payment is TICKET
or BANK_TRANSFER
.type
of the payment is TICKET
or BANK_TRANSFER
.C
: for Current accounts; S
: for Savings accounts; I
: International accounts.
Recommended if the type
of the payment is TICKET
or BANK_TRANSFER
.type
of the payment is TICKET
or BANK_TRANSFER
.{"id" : "REF42342","payment_id" : "PAY4334346343","notification_url" : "http://some.url","amount" : 803.04,"currency" : "BRL","status" : "SUCCESS","status_code" : 200,"status_detail" : "The refund was paid","created_date" : "2018-09-06T22:03:03.000+0000","amount_refunded" : 803.04 //Deprecated}
If any of the following parameters are missing or invalid, dLocal will send an email to the buyer (to the email provided during the Create a Payment) asking them for the information.
Parameters: beneficiary_name
,bank
, bank_account
, bank_account_type
, bank_branch
$ curl -X POST \-H 'X-Date: 2018-02-20T15:44:42.310Z' \-H 'X-Login: sak223k2wdksdl2' \-H 'X-Trans-Key: fm12O7G9' \-H 'X-Version: 2.1' \-H 'User-Agent: MerchantTest / 1.0 ' \-H 'Content-Type: application/json' \-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \https://api.dlocal.com/refunds
{"payment_id" : "PAY4334346343","amount": 100.00,"currency": "USD","notification_url": "http://some.url"}
If a refund is pending, the refund confirmation is sent asynchronously to the refund notification URL by POST, sending the following parameters:
Property | Type | Description |
| String | The refund id. |
| String | The payment id. |
| Positive Float | The amount of the refund. Always in local currency. |
| Positive Float | Deprecated. Do not use. |
| String | The currency code of the refund. |
| String | The status of the refund. |
| String | The status code of the refund. |
| String | The status detail. |
| String | The date of when the refund was executed. |
| String | URL where dlocal will send notifications associated to changes in this refund. |
| String | Description of the refund. |
| String | User's bank name. |
| String | User's bank account number. |
| String | Type of bank account. |
| String | User's bank branch name. |
| String | ID of the payment, given by the merchant in their system. |
POST: {refund.notification_url}
{"id" : "REF42342","payment_id" : "PAY245235","amount" : 803.04,"amount_refunded" : 803.04, //Deprecated"currency" : "BRL","status" : "SUCCESS","status_code" : "200","status_detail" : "The refund was paid.","created_date" : "2018-02-15T15:14:52-00:00","order_id" : "SALE-124635123"}
{"id" : "REF42342","payment_id" : "PAY4334346343","notification_url" : "http://some.url","amount" : 803.04,"currency" : "BRL","status" : "SUCCESS","status_code" : 200,"status_detail" : "The refund was paid","created_date" : "2018-09-06T22:03:03.000+0000","amount_refunded" : 803.04 //Deprecated}
$ 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 'User-Agent: MerchantTest / 1.0 ' \-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \https://api.dlocal.com/refunds/REF42342
{"id": "REF42342","status": "SUCCESS","status_code": "200","status_detail": "The refund was paid."}
Status | Status code | Description |
| 100 | The refund is pending. |
| 200 | The refund was paid. |
| 300 | The refund was rejected. |
| 400 | The refund was cancelled. |
All the errors are returned with appropriate HTTP status code, 4XX or 5XX. The format of all errors is:
Property | Type | Description |
| Integer | Error code. |
| String | Human readable message. |
| String | In case one parameter is wrong. |
Example error
{"code": 5012,"message": "Insufficient funds."}
HTTP Status Code | Error Code | Error Detail |
| 3001 | Invalid Credentials. |
​ | 3002 | Unregistered IP address. |
​ | 3003 | Merchant has no authorization to use this API. |
| 4000 | Payment not found. |
​ | 4001 | Refund not found. |
| 5000 | Invalid request. |
​ | 5001 | Invalid parameter: [parameter_name] |
​ | 5002 | Invalid transaction status. |
​ | 5003 | Country not supported. |
​ | 5004 | Currency not allowed for this country. |
​ | 5005 | User unauthorized due to cadastral situation. |
​ | 5006 | User limit exceeded. |
​ | 5007 | Amount exceeded. |
​ | 5010 | Request timeout. |
​ | 5011 | Order refund id is duplicated. |
​ | 5012 | Insufficient funds. |
​ | 5017 | Invalid API Version |
​ | 5018 | Chargeback in place for this transaction. |
​ | 5020 | Refund period exceeded. |
| 6000 | Too many requests to the API. |
| 7000 | Failed to process the request. |