Refunds

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.
post
Make a Refund
 https://api.dlocal.com/refunds
Request
Response
Request
Body Parameters
payment_id
required
string
The payment id
notification_url
required
string
If a refund is pending, the refund confirmation is sent asynchronously to this URL.
amount
optional
number
Amount to refund. If the amount is empty, then the default is total amount of the payment.
Required if currency is present.
currency
optional
string
Currency of the Amount.
Required if amount is present.
description
optional
string
Description of the refund.
beneficiary_name
optional
string
User's full name.
Recommended if the type of the payment is TICKET or BANK_TRANSFER .
bank
optional
string
User's bank name.
Recommended if the type of the payment is TICKET or BANK_TRANSFER .
bank_account
optional
string
User's bank account number.
Recommended if the type of the payment is TICKET or BANK_TRANSFER .
bank_account_type
optional
string
Type of bank account. C: for Current accounts; S: for Savings accounts; I: International accounts.
Recommended if the type of the payment is TICKET or BANK_TRANSFER .
bank_branch
optional
string
User's bank branch name.
Recommended if the type of the payment is TICKET or BANK_TRANSFER .
Response
200: OK
{
   "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
Example Request
$ 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
Example Request Body
{
    "payment_id" : "PAY4334346343",
    "amount": 100.00,
    "currency": "USD",
    "notification_url": "http://some.url"
}
Refund Asynchronous Notification
If a refund is pending, the refund confirmation is sent asynchronously to the refund notification URL by POST, sending the following parameters:
The Refund Object
Property
Type
Description
id
String
The refund id.
payment_id
String
The payment id.
amount
Positive Float
The amount of the refund. Always in local currency.
amount_refunded
Positive Float
Deprecated. Do not use.
currency
String
The currency code of the refund.
status
String
The status of the refund.
status_code
String
The status code of the refund.
status_detail
String
The status detail.
created_date
String
The date of when the refund was executed.
notification_url
String
URL where dlocal will send notifications associated to changes in this refund.
description
String
Description of the refund.
bank
String
User's bank name.
bank_account
String
User's bank account number.
bank_account_type
String
Type of bank account. C: for Current accounts; S: for Savings accounts; I: International accounts.
bank_branch
String
User's bank branch name.
order_id
String
ID of the payment, given by the merchant in their system.
Example POST
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"
}
get
Retrieve a Refund
 https://api.dlocal.com/refunds/{refund_id}
Retrieve information about a refund.
Request
Response
Request
Path Parameters
refund_id
required
string
The refund id
Response
200: OK
{
   "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
}
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 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    https://api.dlocal.com/refunds/REF42342
get
Retrieve a Refund Status
https://api.dlocal.com/refunds/{refund_id}/status
Retrieve information about the status of a refund.
Request
Response
Request
Path Parameters
refund_id
required
string
The refund id
Response
200: OK
Example Response
{
    "id": "REF42342",
    "status": "SUCCESS",
    "status_code": "200",
    "status_detail": "The refund was paid."
}
Refund Status Codes
Status
Status code
Description
PENDING
100
The refund is pending.
SUCCESS
200
The refund was paid.
REJECTED
300
The refund was rejected.
CANCELLED
400
The refund was cancelled.
Errors
All the errors are returned with appropriate HTTP status code, 4XX or 5XX. The format of all errors is:
Property
Type
Description
code
Integer
Error code.
message
String
Human readable message.
param
String
In case one parameter is wrong.
Example error
{
    "code": 5012,
    "message": "Insufficient funds."
}
Http Errors
HTTP Status Code
Error Code
Error Detail
403 Forbidden
3001
Invalid Credentials.
​
3002
Unregistered IP address.
​
3003
Merchant has no authorization to use this API.
404 Not Found
4000
Payment not found.
​
4001
Refund not found.
400 Bad Request
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.
429 Too many requests
6000
Too many requests to the API.
500 Internal Server Error
7000
Failed to process the request.
Refunds Generic Flow

Mobile Money Payments

Orders

Last updated 5 months ago

Property	Type	Description
`id`	String	The refund id.
`payment_id`	String	The payment id.
`amount`	Positive Float	The amount of the refund. Always in local currency.
`amount_refunded`	Positive Float	Deprecated. Do not use.
`currency`	String	The currency code of the refund.
`status`	String	The status of the refund.
`status_code`	String	The status code of the refund.
`status_detail`	String	The status detail.
`created_date`	String	The date of when the refund was executed.
`notification_url`	String	URL where dlocal will send notifications associated to changes in this refund.
`description`	String	Description of the refund.
`bank`	String	User's bank name.
`bank_account`	String	User's bank account number.
`bank_account_type`	String	Type of bank account. `C`: for Current accounts; `S`: for Savings accounts; `I`: International accounts.
`bank_branch`	String	User's bank branch name.
`order_id`	String	ID of the payment, given by the merchant in their system.

Status	Status code	Description
`PENDING`	100	The refund is pending.
`SUCCESS`	200	The refund was paid.
`REJECTED`	300	The refund was rejected.
`CANCELLED`	400	The refund was cancelled.

Property	Type	Description
`code`	Integer	Error code.
`message`	String	Human readable message.
`param`	String	In case one parameter is wrong.

HTTP Status Code	Error Code	Error Detail
`403 Forbidden`	3001	Invalid Credentials.
	3002	Unregistered IP address.
	3003	Merchant has no authorization to use this API.
`404 Not Found`	4000	Payment not found.
	4001	Refund not found.
`400 Bad Request`	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.
`429 Too many requests`	6000	Too many requests to the API.
`500 Internal Server Error`	7000	Failed to process the request.

Refunds

postMake a Refund

Example Request

Example Request Body

Refund Asynchronous Notification

The Refund Object

Example POST

getRetrieve a Refund

Example Request

getRetrieve a Refund Status

Refund Status Codes

Errors

Http Errors

Refunds Generic Flow

post
Make a Refund

get
Retrieve a Refund

get
Retrieve a Refund Status