Inyo

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.

Hay dos versiones disponibles:

VersiónEndpointDiferencia Clave
v1POST /foreign-exchangeConsulta simple por par de divisas
v2POST /v2/foreign-exchangeIncluye paymentMethod para tasas específicas por método, y monto/país opcionales

v1 — Tasa FX Simple

Devuelve una tasa de cambio para un par de divisas.

Endpoint

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

Encabezados:

EncabezadoValor
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Solicitud

CampoTipoRequeridoDescripción
sourceCurrencyCodestringNoDivisa de origen (ISO 4217, p. ej., "USD")
destinationCurrencyCodestringNoDivisa de destino (ISO 4217, p. ej., "BRL")

Ejemplo de Solicitud

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

Respuesta (200)

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

v2 — Tasa FX Específica por Método de Pago

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

Endpoint

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

Encabezados:

EncabezadoValor
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Solicitud

CampoTipoRequeridoDescripción
sourceCurrencyCodestringSíDivisa de origen (ISO 4217, p. ej., "USD")
destinationCurrencyCodestringSíDivisa de destino (ISO 4217, p. ej., "BRL")
paymentMethodstringSíMétodo de pago para el cálculo de la tasa (ver valores abajo)
sourceCurrencyAmountnumberNoMonto en la divisa de origen — cuando se proporciona, la respuesta incluye el monto de destino convertido
destinationCountryCodestringNoPaís de destino (ISO Alpha-2) — acota la tasa a un corredor específico

Valores de paymentMethod

ValorDescripción
CARDPayout a tarjeta (Visa Direct / Mastercard Send)
CREDIT_CARDTarjeta de crédito
DEBIT_CARDTarjeta de débito
ACHTransferencia bancaria ACH
BANK_ACCOUNTPayout transfronterizo a cuenta bancaria
WALLETPayout a billetera digital
AFTAccount funding transaction
CASHRetiro en efectivo
CHECKCheque
MONEY_ORDERGiro postal
APPLE_PAYApple Pay
GOOGLE_PAYGoogle Pay
OTHEROtro método de pago

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

Respuesta (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"
}

Campos de la Respuesta

CampoTipoDescripción
fxIdstringIdentificador de la cotización FX — pásalo en tu solicitud de pago para fijar la tasa
conversionRatenumberTasa de cambio aplicada
sourceCurrencyCodestringDivisa de origen (solo v2)
sourceCurrencyAmountnumberMonto de origen (solo v2, cuando se proporciona en la solicitud)
destinationCurrencyCodestringDivisa de destino (solo v2)
destinationCurrencyAmountnumberMonto convertido (solo v2, cuando se proporciona sourceCurrencyAmount)
paymentMethodstringMétodo de pago al que aplica la tasa (solo v2)
quoteIdExpiryDateTimestringMarca de tiempo de expiración ISO 8601 — la tasa deja de ser válida después de ese momento

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

PreviousBalanceNextPago