---
description: >-
  Retrieve real-time foreign exchange rates for cross-currency transactions
  using POST /foreign-exchange (v1) or POST /v2/foreign-exchange (v2). The v2
  endpoint supports payment-method-specific rates.
---

# Foreign Exchange

The Foreign Exchange API returns real-time FX rates for cross-currency payments. Use the rate and `fxId` in your [Push Transaction](payment/push-transaction.md) or [Pull and Push](payment/pull-and-push-in-one-step.md) request.

Two versions are available:

| Version | Endpoint | Key Difference |
|---|---|---|
| **v1** | `POST /foreign-exchange` | Simple currency-pair lookup |
| **v2** | `POST /v2/foreign-exchange` | Includes `paymentMethod` for method-specific rates and optional amount/country |

---

## v1 — Simple FX Rate

Returns an exchange rate for a currency pair.

### Endpoint

```
POST https://{FQDN}/foreign-exchange
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `sourceCurrencyCode` | string | ❌ | Source currency (ISO 4217, e.g., `"USD"`) |
| `destinationCurrencyCode` | string | ❌ | Destination currency (ISO 4217, e.g., `"BRL"`) |

### Example Request

```bash
curl -X POST https://{FQDN}/foreign-exchange \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "BRL"
  }'
```

### Response (200)

```json
{
  "fxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "conversionRate": 4.975,
  "quoteIdExpiryDateTime": "2025-03-31T15:30:00Z"
}
```

---

## v2 — Payment-Method-Specific FX Rate

Returns an exchange rate tailored to the payment method. Different methods (card, ACH, PIX, wallet) may carry different FX spreads.

### Endpoint

```
POST https://{FQDN}/v2/foreign-exchange
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `sourceCurrencyCode` | string | ✅ | Source currency (ISO 4217, e.g., `"USD"`) |
| `destinationCurrencyCode` | string | ✅ | Destination currency (ISO 4217, e.g., `"BRL"`) |
| `paymentMethod` | string | ✅ | Payment method for rate calculation (see values below) |
| `sourceCurrencyAmount` | number | ❌ | Amount in source currency — when provided, the response includes the converted destination amount |
| `destinationCountryCode` | string | ❌ | Destination country (ISO Alpha-2) — narrows the rate to a specific corridor |

### `paymentMethod` Values

| Value | Description |
|---|---|
| `CARD` | Card payout (Visa Direct / Mastercard Send) |
| `CREDIT_CARD` | Credit card |
| `DEBIT_CARD` | Debit card |
| `ACH` | ACH bank transfer |
| `BANK_ACCOUNT` | Cross-border bank account payout |
| `WALLET` | Digital wallet payout |
| `AFT` | Account funding transaction |
| `CASH` | Cash pickup |
| `CHECK` | Check |
| `MONEY_ORDER` | Money order |
| `APPLE_PAY` | Apple Pay |
| `GOOGLE_PAY` | Google Pay |
| `OTHER` | Other payment method |

### Example — Rate for Card Payout

```bash
curl -X POST https://{FQDN}/v2/foreign-exchange \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "BRL",
    "paymentMethod": "CARD"
  }'
```

### Example — Rate with Amount and Country

```bash
curl -X POST https://{FQDN}/v2/foreign-exchange \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrencyCode": "USD",
    "sourceCurrencyAmount": 100.00,
    "destinationCurrencyCode": "PHP",
    "destinationCountryCode": "PH",
    "paymentMethod": "WALLET"
  }'
```

### Response (200)

```json
{
  "fxId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "conversionRate": 56.42,
  "sourceCurrencyCode": "USD",
  "sourceCurrencyAmount": 100.00,
  "destinationCurrencyCode": "PHP",
  "destinationCurrencyAmount": 5642.00,
  "paymentMethod": "WALLET",
  "quoteIdExpiryDateTime": "2025-03-31T15:30:00Z"
}
```

---

## Response Fields

| Field | Type | Description |
|---|---|---|
| `fxId` | string | FX quote identifier — pass this in your payment request to lock in the rate |
| `conversionRate` | number | Exchange rate applied |
| `sourceCurrencyCode` | string | Source currency (v2 only) |
| `sourceCurrencyAmount` | number | Source amount (v2 only, when provided in request) |
| `destinationCurrencyCode` | string | Destination currency (v2 only) |
| `destinationCurrencyAmount` | number | Converted amount (v2 only, when `sourceCurrencyAmount` provided) |
| `paymentMethod` | string | Payment method the rate applies to (v2 only) |
| `quoteIdExpiryDateTime` | string | ISO 8601 expiry timestamp — the rate is invalid after this time |

## Usage in Payments

Pass the `fxId` and `conversionRate` from the response into your payment request:

- `fxId` → payment `fxId` field
- `conversionRate` → payment `exchangeRate` field

> **Note:** FX quotes have a limited validity period. Check `quoteIdExpiryDateTime` and request a new quote if expired before submitting the payment.

## What's Next

- [Push Transaction](payment/push-transaction.md) — Send cross-currency payouts
- [Pull and push in one step](payment/pull-and-push-in-one-step.md) — Collect and disburse in a single call
- [Balance](balance.md) — Check available funds before transacting