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

<br />

Configuration required: to use the Quote API, please contact your Technical Account Manager or email us at 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:

// Step 1: Create quote with source_amount
POST /payouts/v3/quote
{
"country": "MY",
"source_currency": "USD",
"destination_currency": "MYR",
"source_amount": 100
}

// Response
{
"id": "cos9d7UH1J07FbJPh5HZ98gzebpHytFsTlfr",
"details": {
  "source_amount": 100,
  "source_currency": "USD",
  "destination_amount": 392.72,
  "destination_currency": "MYR"
}
}

// 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:

// Step 2: Create payout (CORRECT)
POST /payouts/v3
{
"quote_id": "cos9d7UH1J07FbJPh5HZ98gzebpHytFsTlfr",
"currency": "USD",      // ✅ Matches source_currency
"amount": 100           // ✅ Matches source_amount
}

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

{
  "status_code": "200",
  "status": "CREATED",
  "status_detail": "Quote created successfully",
  "id": "60sYJU1pTCPB3vJoOFG0XCBox9SdMJbznxb0",
  "created_date": "2023-09-05T17:21:29.000+0000",
  "expiration_date": "2023-09-06T17:21:29.000+0000",
  "details": {
    "country": "CO",
    "source_amount": 100,
    "source_currency": "USD",
    "destination_amount": 419439.11,
    "destination_currency": "COP",
    "exchange_rate": 4194.3911,
    "exchange_rate_official": 4214.6213,
    "country_markup_percentage": 0.48,
    "exchange_rate_spread": 20.2301
  },
  "fees": {
    "amount": 1.6,
    "currency": "USD"
  },
  "taxes": {
    "amount": 0.09,
    "currency": "USD"
  },
  "debit": {
    "amount": 101.69,
    "currency": "USD"
  }
}