Docs
Search the docs
Find a page in the docs

Guides

Currency conversion

Price in one currency and charge in another with a locked exchange-rate quote.

Price in one currency and charge in another: list a product at USD 100.00 and charge the equivalent in ARS through Mercado Pago. Camel locks the rate in a quote, so the customer pays exactly what you showed them.

1. Create a quote

Send the price and both currencies. A quote is valid for 15 minutes:

curl -X POST https://api.camelpayment.com/v1/fx/quotes \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "source_currency": "USD",
    "target_currency": "ARS"
  }'
201 Created
{
  "id": "fxq_01JBXA7K2M4N6P8R0T2V4X6Z8B",
  "object": "fx_quote",
  "source_amount": 10000,
  "source_currency": "USD",
  "target_amount": 15400000,
  "target_currency": "ARS",
  "rate": "1540.0000000000",
  "market_rate": "1540.0000000000",
  "spread_bps": 0,
  "rates_as_of": "2026-11-12T15:00:00Z",
  "expires_at": "2026-11-12T15:19:05Z",
  "created_at": "2026-11-12T15:04:05Z"
}

rate is what the customer gets, including any spread you set in the dashboard (spread_bps, in basis points); market_rate is the rate before it.

2. Charge the quote

Create the payment for the quote's target_amount and target_currency, and pass its id as fx_quote_id:

curl -X POST https://api.camelpayment.com/v1/payments \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: order-1525" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mercadopago",
    "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
    "amount": 15400000,
    "currency": "ARS",
    "fx_quote_id": "fxq_01JBXA7K2M4N6P8R0T2V4X6Z8B",
    "payment_method": {
      "type": "card",
      "token": "ff8080814c11e237014c1ff593b57b4d"
    }
  }'

The payment's conversion field records the original price and rate: quote_id, pricing_amount, pricing_currency, and rate.

An expired quote returns 409, and an amount or currency that doesn't match the quote returns 422. Create a new quote and show the customer the new price.

Checkouts

Checkouts can convert on their own. Turn on currency conversion for the project in the dashboard and create the checkout in your pricing currency; when the provider can't charge it, Camel quotes the conversion and shows it in the checkout's charge field.

Exchange rates

To show approximate prices before quoting, read the current rates with List exchange rates. Rates come from public sources and refresh every hour.