Inyo

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.

Two versions are available:

VersionEndpointKey Difference
v1POST /foreign-exchangeSimple currency-pair lookup
v2POST /v2/foreign-exchangeIncludes 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:

HeaderValue
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Request

FieldTypeRequiredDescription
sourceCurrencyCodestring❌Source currency (ISO 4217, e.g., "USD")
destinationCurrencyCodestring❌Destination currency (ISO 4217, e.g., "BRL")

Example Request

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

Response (200)

{
  "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:

HeaderValue
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Request

FieldTypeRequiredDescription
sourceCurrencyCodestring✅Source currency (ISO 4217, e.g., "USD")
destinationCurrencyCodestring✅Destination currency (ISO 4217, e.g., "BRL")
paymentMethodstring✅Payment method for rate calculation (see values below)
sourceCurrencyAmountnumber❌Amount in source currency — when provided, the response includes the converted destination amount
destinationCountryCodestring❌Destination country (ISO Alpha-2) — narrows the rate to a specific corridor

paymentMethod Values

ValueDescription
CARDCard payout (Visa Direct / Mastercard Send)
CREDIT_CARDCredit card
DEBIT_CARDDebit card
ACHACH bank transfer
BANK_ACCOUNTCross-border bank account payout
WALLETDigital wallet payout
AFTAccount funding transaction
CASHCash pickup
CHECKCheck
MONEY_ORDERMoney order
APPLE_PAYApple Pay
GOOGLE_PAYGoogle Pay
OTHEROther payment method

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

Response (200)

{
  "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

FieldTypeDescription
fxIdstringFX quote identifier — pass this in your payment request to lock in the rate
conversionRatenumberExchange rate applied
sourceCurrencyCodestringSource currency (v2 only)
sourceCurrencyAmountnumberSource amount (v2 only, when provided in request)
destinationCurrencyCodestringDestination currency (v2 only)
destinationCurrencyAmountnumberConverted amount (v2 only, when sourceCurrencyAmount provided)
paymentMethodstringPayment method the rate applies to (v2 only)
quoteIdExpiryDateTimestringISO 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

PreviousBalanceNextPayment