--- title: "Create a quote" method: POST path: "/payouts/v3/quote" tags: ["Currency exchange"] --- # Create a quote `POST /payouts/v3/quote` ## Request - Base URL: `https://api.dlocal.com` - URL: `https://api.dlocal.com/payouts/v3/quote` - Auth: API key in header `X-Date` and API key in header `X-Version` and API key in header `Authorization` This endpoint generates an FX rate for a particular currency pair. --- When this service is called, it returns a `quote_id`, which uniquely identifies the quoted foreign exchange (FX) rate, including any applicable fees and taxes. This `quote_id` can be used in subsequent requests to create Payouts, as long as it remains within the quote's validity period. There are three possible ways to create a quote ID configuration: - Request with no amount specified - Request specifying the source amount - Request specifying the destination amount
> **Configuration required**: to use the Quote API, please contact your Technical Account Manager or email us at [integrations@dlocal.com](mailto:integrations@dlocal.com) to request setup. ## ⚠️ IMPORTANT: Quote-to-Payout Currency Contract **The amount type you specify when creating the quote determines which currency and amount you MUST use in the subsequent payout request.** ### Rules: 1. **Quote created with **`source_amount`**:** - Payout **MUST** use: `currency = source_currency` and `amount = source_amount` - Example: Quote with `source_amount=100, source_currency=USD` → Payout with `currency=USD, amount=100` 2. **Quote created with **`destination_amount`**:** - Payout **MUST** use: `currency = destination_currency` and `amount = destination_amount` - Example: Quote with `destination_amount=392.72, destination_currency=MYR` → Payout with `currency=MYR, amount=392.72` 3. **Quote created with no amount:** - Payout can use either `source_currency` or `destination_currency` - The exchange rate will be applied accordingly ### Common Error: ❌ **Error Code 109**: `QUOTE_ID_AND_PAYOUT_TARGET_CURRENCY_MISMATCH` This error occurs when: - You create a quote with `source_amount` but send the payout with `destination_currency` - You create a quote with `destination_amount` but send the payout with `source_currency` **Example of incorrect usage:** ```json // Step 1: Create quote with source_amount POST /payouts/v3/quote { "country": "MY", "source_currency": "USD", "destination_currency": "MYR", "source_amount": 100 } ``` ```json // Response { "id": "cos9d7UH1J07FbJPh5HZ98gzebpHytFsTlfr", "details": { "source_amount": 100, "source_currency": "USD", "destination_amount": 392.72, "destination_currency": "MYR" } } ``` ```json // Step 2: Create payout (INCORRECT - will fail with error 109) POST /payouts/v3 { "quote_id": "cos9d7UH1J07FbJPh5HZ98gzebpHytFsTlfr", "currency": "MYR", // ❌ WRONG - should be USD "amount": 392.72 // ❌ WRONG - should be 100 } ``` **Correct usage:** ```json // Step 2: Create payout (CORRECT) POST /payouts/v3 { "quote_id": "cos9d7UH1J07FbJPh5HZ98gzebpHytFsTlfr", "currency": "USD", // ✅ Matches source_currency "amount": 100 // ✅ Matches source_amount } ``` ## Request body - CreateQuoteRequest - `country` string, required: Country code of the destination. ISO-3166 country code ISO-3166 country code. - `source_currency` string: Currency code for the source amount. ISO-4217 currency code. - `destination_currency` string, required: Currency code for the destination amount. ISO-4217 currency code. - `source_amount` number, float: Payout source amount expressed in the currency indicated in `source_currency`. When creating a payout, specify the exact same amount specified in this parameter. - `destination_amount` number, float: Payout destination amount expressed in the currency indicated in `destination_currency`. When creating a payout, specify the exact same amount specified in this parameter. ## Response `200` Quote created - ResponseCreateQuote - `status_code` string, int: Quote generation status code. - `status` string: Quote generation status description. - `status_detail` string: Quote generation status detail. - `id` string: Unique ID generated for the quoted FX rate. - `created_date` string, date-time: Creation date and time for the quoted FX rate. - `expiration_date` string, date-time: Expiration date and time for the quoted FX rate. - `details` QuoteDetails - `country` string, ISO-3166 country code: Country code of the destination. - `source_amount` number: Payout source amount expressed in the currency indicated in source_currency. - `source_currency` string, ISO-4217 currency code: Currency code for the source amount. - `destination_amount` number: Payout destination amount expressed in the currency indicated in destination_currency. - `destination_currency` string, ISO-4217 currency code: Currency code for the destination amount. - `exchange_rate` number: dLocal's FX rate for the requested currency pair with the markup applied. - `exchange_rate_official` number: Official FX rate for the requested currency pair. - `country_markup_percentage` number: Markup rate for the destination currency, expressed as a percentage. - `exchange_rate_spread` number: dLocal's spread resulting from the application of the markup to the official FX rate. - `fees` Fees - `amount` number: Total fees amount applicable to the transaction. - `currency` string, ISO-4217 currency code: Currency for the total processing fees. - `taxes` Taxes - `amount` number: Total tax amount applicable to the transaction. - `currency` string, ISO-4217 currency code: Currency for the total taxes applied. - `debit` Debit - `amount` number: Total amount that would be debited from the merchant's balance. - `currency` string, ISO-4217 currency code: Currency for the debit to the merchant's balance. ## Other responses - `400`: Bad Request - `403`: Forbidden --- [API](https://skmtc.dev/dlocal/apis/payouts-v3.md) - [All operations](https://skmtc.dev/dlocal/apis/payouts-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/dlocal/apis/payouts-v3/revisions/02c74e9e986e?raw)