Overview

When submitting a payout, you can set a foreign exchange (FX) rate quote for a specific currency pair.

It includes dLocal’s markup and can be valid for an agreed amount of time. Each quote can be used for multiple payouts if it's still valid by referencing the quote ID.

If the source or destination amount is provided it will also return and freeze the complete breakdown of fees and taxes that would apply to a payout.

📘

Quote availability

This service covers conversions from USD to local currencies in all dLocal's operating countries, except Argentina.

How it works

The steps required to use quotes are:

1. Call the Quote API to obtain an FX rate quote for a specific currency pair. The generated quote includes a unique quote_id.
   1. If no amount is provided, only the FX rate details are quoted and locked for the validity period of the quote_id.
   2. If the source or destination amount is provided, the quote_id will quote and hold the FX rate, applicable fees, and taxes.
2. Submit payout requests adding the quote_id to the payout request body, to apply the previously quoted FX rate, fees, and taxes to the transaction.
   1. Once the quote’s validity period is finished, it expires and will no longer be able to be applied to payout requests. Validity periods are customizable depending on businesses’ characteristics.

Usage scenarios

There are three possible ways to create a quote ID configuration. The required fields can change based on how the service will be used.

📘

Difference between source and destination currency

Source currency. The currency in which the payout balance is held. USD is the only accepted value.
Destination currency. The local currency in which the end user will receive the payout.

No amount specified

If you don't want to specify the amount, send only the destination country and the currency pair of interest. As a response, the complete FX rate quote details are returned.

In this case, the applicable fees, taxes, and the amount to be debited from the balance cannot be calculated, because neither the source nor the destination amounts are provided.

Example request

{
   "country":"CO",
   "source_currency":"USD",
   "destination_currency":"COP"
}

{
   "status": "0",
   "desc": "OK",
   "quote_id": "60sYJU1pTCPB3vJoOFG0XCBox9SdMJbznxb0",
   "creation_time": "2024-04-04T16:33:13.038Z",
   "expiration_time": "2024-04-05T16:33:13.038Z",
   "detail": {
         "source_amount": 1.00,
         "source_currency": "USD",
         "destination_amount": 4194.39,
         "destination_currency": "COP",
         "exchange_rate": 4194.3911
   }
}

{
    "status": 300,
    "desc": "Empty params",
    "error_code": 301
}

Source amount specified

If you want to determine the source amount, send the destination country, the currency pair of interest, and the source amount.

As a response, it returns the complete FX rate quote details, as well as the calculation of the destination amount, the applicable fees and taxes, and the total amount to be debited from the balance.

{
   "country":"CO",
   "source_currency":"USD",
   "destination_currency":"COP",
   "source_amount": 100
}

{  
   "status": "0",
   "desc": "OK",
   "quote_id":"60sYJU1pTCPB3vJoOFG0XCBox9SdMJbznxb0",
   "creation_time":"2024-04-04T16:33:13.038Z",
   "expiration_time":"2024-04-05T16:33:13.038Z",
   "detail": {
         "source_amount": 100,
         "source_currency":"USD",
         "destination_amount": 419439.11,
         "destination_currency":"COP",
         "exchange_rate": 4194.3911
   },
   "fee": {
         "fee_amount": 1.6,
         "fee_currency":"USD"
   },
   "tax": {
         "tax_amount": 0.09,
         "tax_currency":"USD"
   },
   "debit": {
         "debit_amount": 101.69,
         "debit_currency":"USD"
   }
}

{
    "status": 300,
    "desc": "Empty params",
    "error_code": 301
}

Destination amount specified

If you want to determine the destination amount, send the destination country, the currency pair of interest, and the destination amount.

As a response, it returned the complete FX rate quote details, as well as the calculation of the destination amount, the applicable fees and taxes, and the total amount to be debited from the balance.

When requesting a quote with a destination amount, please note that the source_amount resulting from the calculation will be rounded up to the nearest hundredth (i.e., two decimal places). The final requested amount will be guaranteed.

{
   "country":"CO",
   "source_currency":"USD",
   "destination_currency":"COP",
   "destination_amount": 500000
}

{  
   "status": "0",
   "desc": "OK",
   "quote_id":"60sYJU1pTCPB3vJoOFG0XCBox9SdMJbznxb0",
   "creation_time":"2024-04-04T16:33:13.038Z",
   "expiration_time":"2024-04-05T16:33:13.038Z",
   "detail": {
         "source_amount": 119.21,
         "source_currency":"USD",
         "destination_amount": 500000,
         "destination_currency":"COP",
         "exchange_rate": 4194.3911
   },
   "fee": {
         "fee_amount": 1.6,
         "fee_currency":"USD"
   },
   "tax": {
         "tax_amount": 0.09,
         "tax_currency":"USD"
   },
   "debit": {
         "debit_amount": 120.9,
         "debit_currency":"USD"
   }
}

{
    "status": 300,
    "desc": "Empty params",
    "error_code": 301
}