Inyo

Foreign Exchange

A API Foreign Exchange retorna taxas de câmbio em tempo real para pagamentos entre moedas. Use a taxa e o fxId na sua requisição de Push Transaction ou Pull and Push.

Duas versões estão disponíveis:

VersãoEndpointDiferença Principal
v1POST /foreign-exchangeConsulta simples de par de moedas
v2POST /v2/foreign-exchangeInclui paymentMethod para taxas específicas por método e valor/país opcionais

v1 — Taxa de Câmbio Simples

Retorna uma taxa de câmbio para um par de moedas.

Endpoint

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

Cabeçalhos:

CabeçalhoValor
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Requisição

CampoTipoObrigatórioDescrição
sourceCurrencyCodestringNãoMoeda de origem (ISO 4217, ex.: "USD")
destinationCurrencyCodestringNãoMoeda de destino (ISO 4217, ex.: "BRL")

Exemplo de Requisição

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

Resposta (200)

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

v2 — Taxa de Câmbio Específica por Método de Pagamento

Retorna uma taxa de câmbio ajustada ao método de pagamento. Métodos diferentes (cartão, ACH, PIX, carteira) podem ter spreads de câmbio diferentes.

Endpoint

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

Cabeçalhos:

CabeçalhoValor
AuthorizationBearer {accessToken}
Content-Typeapplication/json

Requisição

CampoTipoObrigatórioDescrição
sourceCurrencyCodestringSimMoeda de origem (ISO 4217, ex.: "USD")
destinationCurrencyCodestringSimMoeda de destino (ISO 4217, ex.: "BRL")
paymentMethodstringSimMétodo de pagamento para o cálculo da taxa (veja os valores abaixo)
sourceCurrencyAmountnumberNãoValor na moeda de origem — quando fornecido, a resposta inclui o valor de destino convertido
destinationCountryCodestringNãoPaís de destino (ISO Alpha-2) — restringe a taxa a um corredor específico

Valores de paymentMethod

ValorDescrição
CARDPayout para cartão (Visa Direct / Mastercard Send)
CREDIT_CARDCartão de crédito
DEBIT_CARDCartão de débito
ACHTransferência bancária ACH
BANK_ACCOUNTPayout internacional para conta bancária
WALLETPayout para carteira digital
AFTAccount funding transaction
CASHRetirada em dinheiro
CHECKCheque
MONEY_ORDEROrdem de pagamento
APPLE_PAYApple Pay
GOOGLE_PAYGoogle Pay
OTHEROutro método de pagamento

Exemplo — Taxa para Payout em Cartão

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

Exemplo — Taxa com Valor e 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"
  }'

Resposta (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 da Resposta

CampoTipoDescrição
fxIdstringIdentificador da cotação de câmbio — passe-o na sua requisição de pagamento para travar a taxa
conversionRatenumberTaxa de câmbio aplicada
sourceCurrencyCodestringMoeda de origem (somente v2)
sourceCurrencyAmountnumberValor de origem (somente v2, quando fornecido na requisição)
destinationCurrencyCodestringMoeda de destino (somente v2)
destinationCurrencyAmountnumberValor convertido (somente v2, quando sourceCurrencyAmount é fornecido)
paymentMethodstringMétodo de pagamento ao qual a taxa se aplica (somente v2)
quoteIdExpiryDateTimestringTimestamp de expiração ISO 8601 — a taxa é inválida após este horário

Uso em Pagamentos

Passe o fxId e o conversionRate da resposta para a sua requisição de pagamento:

  • fxId → campo fxId do pagamento
  • conversionRate → campo exchangeRate do pagamento

Nota: as cotações de câmbio têm um período de validade limitado. Verifique quoteIdExpiryDateTime e solicite uma nova cotação se estiver expirada antes de submeter o pagamento.

Próximos Passos

PreviousBalanceNextPagamento