Foreign Exchange

The Foreign Exchange API returns real-time FX rates for cross-currency payments. Use the rate and fxId in your Push Transaction or Pull and Push request.

Requesting a Rate

Returns an exchange rate tailored to the payment method. Different methods (bank account, wallet, card) 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	Yes	Source currency (ISO 4217, e.g., `"USD"`)
`destinationCurrencyCode`	string	Yes	Destination currency (ISO 4217, e.g., `"BRL"`)
`paymentMethod`	string	Yes	Payment method for rate calculation (see values below)
`sourceCurrencyAmount`	number	No	Amount in source currency. Accepted as a number or a quoted string (`20.00` and `"20.00"` both work). It does not change the response — compute the destination amount yourself as `sourceCurrencyAmount × conversionRate`
`destinationCountryCode`	string	No	Destination country, ISO 3166-1 alpha-3 (e.g., `"KEN"`, `"PHL"`) — narrows the rate to a specific corridor. A two-letter code is rejected with `PAY_001`

`paymentMethod` Values

Value	Description
`BANK_ACCOUNT`	Cross-border bank account payout
`WALLET`	Digital wallet payout
`CARD`	Card payout

These three are the accepted values. Any other value is rejected with PAY_005 — Payment method not found for description.

A PAY_001 — No router found for agent and payment method means the opposite: the method is valid, but your account has no route for that method on that corridor.

Example — Rate for Card Payout

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

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": "PHL",
    "paymentMethod": "WALLET"
  }'

Response (200)

{
  "fxId": "763eea51-4c57-4fbc-9729-6484b06daac2",
  "conversionRate": 59.57535,
  "sourceCurrencyCode": "USD",
  "destinationCurrencyCode": "PHP",
  "quoteIdExpiryDateTime": "2026-08-11T14:49:06.490Z"
}

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
`destinationCurrencyCode`	string	Destination currency
`quoteIdExpiryDateTime`	string	ISO 8601 expiry timestamp — the rate is invalid after this time

These five fields are the entire response. It does not echo sourceCurrencyAmount, destinationCurrencyAmount, or paymentMethod — the converted amount is never returned. To fill recipientAmount.total on the payment, multiply it yourself:

recipientAmount.total = sourceCurrencyAmount × conversionRate

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 — Send cross-currency payouts
Pull and push in one step — Collect and disburse in a single call
Balance — Check available funds before transacting