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.

Solicitar uma Taxa

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

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Requisição

Campo	Tipo	Obrigatório	Descrição
`sourceCurrencyCode`	string	Sim	Moeda de origem (ISO 4217, ex.: `"USD"`)
`destinationCurrencyCode`	string	Sim	Moeda de destino (ISO 4217, ex.: `"BRL"`)
`paymentMethod`	string	Sim	Método de pagamento para o cálculo da taxa (veja os valores abaixo)
`sourceCurrencyAmount`	number	Não	Valor na moeda de origem. Aceito como número ou como string entre aspas (`20.00` e `"20.00"` funcionam). Não altera a resposta — calcule o valor de destino você mesmo como `sourceCurrencyAmount × conversionRate`
`destinationCountryCode`	string	Não	País de destino, ISO 3166-1 alfa-3 (ex.: `"KEN"`, `"PHL"`) — restringe a taxa a um corredor específico. Um código de duas letras é rejeitado com `PAY_001`

Valores de `paymentMethod`

Valor	Descrição
`BANK_ACCOUNT`	Payout internacional para conta bancária
`WALLET`	Payout para carteira digital
`CARD`	Payout para cartão

Estes três são os valores aceitos. Qualquer outro valor é rejeitado com PAY_005 — Payment method not found for description.

Um PAY_001 — No router found for agent and payment method significa o oposto: o método é válido, mas a sua conta não tem rota para esse método naquele corredor.

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

Resposta (200)

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

Campos da Resposta

Campo	Tipo	Descrição
`fxId`	string	Identificador da cotação de câmbio — passe-o na sua requisição de pagamento para travar a taxa
`conversionRate`	number	Taxa de câmbio aplicada
`sourceCurrencyCode`	string	Moeda de origem
`destinationCurrencyCode`	string	Moeda de destino
`quoteIdExpiryDateTime`	string	Timestamp de expiração ISO 8601 — a taxa é inválida após este horário

Esses cinco campos são a resposta inteira. Ela não devolve sourceCurrencyAmount, destinationCurrencyAmount nem paymentMethod — o valor convertido nunca é retornado. Para preencher recipientAmount.total no pagamento, calcule você mesmo:

recipientAmount.total = sourceCurrencyAmount × conversionRate

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

Push Transaction — Envie payouts entre moedas
Pull e push em uma única etapa — Cobre e desembolse em uma única chamada
Balance — Verifique os fundos disponíveis antes de transacionar