Create a Refund

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

For alternative payment methods, refunds are made through the processor's API when supported, or via bank transfer to the customer when it is not. A refund processing fee may apply.

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 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: 2025-01-15T10:00:00.000Z' \
    -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"
}

Synchronous Response

A refund is returned as PENDING when it can't be confirmed immediately — for example, cash and bank transfer refunds (which require a payout to the customer) are always PENDING on the synchronous response, and some alternative payment methods confirm the final result asynchronously depending on the provider.

Some card refunds and alternative payment methods return a final status (SUCCESS/REJECTED) right away. However, this can vary by payment method, processor, and merchant configuration — in some cases the refund is also returned as PENDING and confirmed later via notification.

While a refund is PENDING, you can poll its status via Check refund status or wait for the asynchronous notification described below.

Refund asynchronous notification

If a refund is pending, the refund confirmation is sent asynchronously to the refund notification URL by POST, sending the parameters below (some of them included in The Refund Object parameters). Please note that notification parameters may vary.

Refund notifications follow the same structure, signature, and retry behavior as payment notifications.

Example POST

POST: {refund.notification_url}

{ 
  "id": "REF42342", 
  "payment_id": "PAY245235", 
  "order_refund_id": "GG1234567890", 
  "notification_url": "https://localhost.com", 
  "amount": 803.04, 
  "currency": "BRL",
  "status": "SUCCESS", 
  "status_code": 200, 
  "status_detail": "The refund was paid.", 
  "created_date": "2024-12-26T18:32:22.000+0000", 
  "amount_refunded": 803.04, 
  "use_orig_fx": false, 
  "payment_request_amount": 803.04, 
  "payment_request_currency": "BRL", 
  "transaction_id": "019444231-9999-11aa-aa1a-c4da1f123456", 
  "authorization_code": "200000", 
  "document_number": "11111111", 
  "order_id": "019444231-9999-11aa-aa1a-c4da1f123456" 
}

Retrieve a refund

Example request

$ curl \
    -H 'X-Date: 2025-01-15T10:00:00.000Z' \
    -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

Refunds Generic Flow