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
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 .
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.

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"
}

get
Retrieve a Refund

https://api.dlocal.com/refunds/{refund_id}
Retrieve information about a refund.
Request
Response
Path Parameters
refund_id
required
string
The refund id
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
Path Parameters
refund_id
required
string
The refund id
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.

429 Too many requests

6000

Too many requests to the API.

500 Internal Server Error

7000

Failed to process the request.