Foreign Exchange

La API Foreign Exchange devuelve tasas de cambio (FX) en tiempo real para pagos entre divisas. Usa la tasa y el fxId en tu solicitud de Push Transaction o Pull and Push.

Solicitar una Tasa

Devuelve una tasa de cambio ajustada al método de pago. Métodos diferentes (cuenta bancaria, billetera, tarjeta) pueden llevar spreads de FX diferentes.

Endpoint

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

Encabezados:

Encabezado	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Solicitud

Campo	Tipo	Requerido	Descripción
`sourceCurrencyCode`	string	Sí	Divisa de origen (ISO 4217, p. ej., `"USD"`)
`destinationCurrencyCode`	string	Sí	Divisa de destino (ISO 4217, p. ej., `"BRL"`)
`paymentMethod`	string	Sí	Método de pago para el cálculo de la tasa (ver valores abajo)
`sourceCurrencyAmount`	number	No	Monto en la divisa de origen. Se acepta como número o como cadena entre comillas (`20.00` y `"20.00"` funcionan). No cambia la respuesta — calcula tú el monto de destino como `sourceCurrencyAmount × conversionRate`
`destinationCountryCode`	string	No	País de destino, ISO 3166-1 alfa-3 (p. ej., `"KEN"`, `"PHL"`) — acota la tasa a un corredor específico. Un código de dos letras se rechaza con `PAY_001`

Valores de `paymentMethod`

Valor	Descripción
`BANK_ACCOUNT`	Payout transfronterizo a cuenta bancaria
`WALLET`	Payout a billetera digital
`CARD`	Payout a tarjeta

Estos tres son los valores aceptados. Cualquier otro valor se rechaza con PAY_005 — Payment method not found for description.

Un PAY_001 — No router found for agent and payment method significa lo contrario: el método es válido, pero tu cuenta no tiene ruta para ese método en ese corredor.

Ejemplo — Tasa para Payout a Tarjeta

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

Ejemplo — Tasa con Monto y País

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

Respuesta (200)

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

Campos de la Respuesta

Campo	Tipo	Descripción
`fxId`	string	Identificador de la cotización FX — pásalo en tu solicitud de pago para fijar la tasa
`conversionRate`	number	Tasa de cambio aplicada
`sourceCurrencyCode`	string	Divisa de origen
`destinationCurrencyCode`	string	Divisa de destino
`quoteIdExpiryDateTime`	string	Marca de tiempo de expiración ISO 8601 — la tasa deja de ser válida después de ese momento

Estos cinco campos son toda la respuesta. No devuelve sourceCurrencyAmount, destinationCurrencyAmount ni paymentMethod — el monto convertido nunca se devuelve. Para llenar recipientAmount.total en el pago, calcúlalo tú:

recipientAmount.total = sourceCurrencyAmount × conversionRate

Uso en Pagos

Pasa el fxId y el conversionRate de la respuesta a tu solicitud de pago:

fxId → campo fxId del pago
conversionRate → campo exchangeRate del pago

Nota: Las cotizaciones FX tienen un período de validez limitado. Verifica quoteIdExpiryDateTime y solicita una nueva cotización si expiró antes de enviar el pago.

Qué Sigue

Push Transaction — Envía payouts entre divisas
Pull y push en un solo paso — Cobra y dispersa en una sola llamada
Balance — Verifica los fondos disponibles antes de transaccionar