# 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**

```bash
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"
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/fx/quotes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 10000,
    "source_currency": "USD",
    "target_currency": "ARS"
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/fx/quotes",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
    },
    json={
        "amount": 10000,
        "source_currency": "USD",
        "target_currency": "ARS"
    },
)
data = response.json()
```

**201 Created**

```json
{
  "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**

```bash
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"
    }
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Idempotency-Key': 'order-1525',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "provider": "mercadopago",
    "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
    "amount": 15400000,
    "currency": "ARS",
    "fx_quote_id": "fxq_01JBXA7K2M4N6P8R0T2V4X6Z8B",
    "payment_method": {
      "type": "card",
      "token": "ff8080814c11e237014c1ff593b57b4d"
    }
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
        "Idempotency-Key": "order-1525",
    },
    json={
        "provider": "mercadopago",
        "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
        "amount": 15400000,
        "currency": "ARS",
        "fx_quote_id": "fxq_01JBXA7K2M4N6P8R0T2V4X6Z8B",
        "payment_method": {
            "type": "card",
            "token": "ff8080814c11e237014c1ff593b57b4d"
        }
    },
)
data = response.json()
```

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

> **Warning**
>
> 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](https://camelpayment.com/docs/api-reference/list-exchange-rates.md). Rates come from public sources and refresh every hour.
