Múltiplas moedas e cotações FX
Quick Reference
Por que oferecer múltiplas moedas
Seus clientes abandonam o checkout quando veem preços em moeda estrangeira. Múltiplas moedas resolvem esse problema.
| Sem múltiplas moedas | Com múltiplas moedas A55 |
|---|---|
| Cliente vê R$ 500,00 mas paga em USD | Cliente vê US$ 87,26 — o valor exato que ele paga |
| Cliente não sabe a taxa de câmbio real | Você mostra a taxa de mercado com total transparência |
| Cliente liga para o banco para contestar o valor | Sem surpresas — o preço corresponde à cobrança |
| Você perde vendas internacionais | Você converte visitantes internacionais em clientes pagantes |
O impacto no negócio é mensurável:
- Maior conversão: clientes compram quando entendem o preço na própria moeda.
- Menos chargebacks: precificação transparente reduz disputas do tipo "não reconheço esse valor".
- Vantagem competitiva: você oferece a mesma experiência de plataformas globais como Amazon, Shopify e Stripe.
- Cobertura LATAM: 8 moedas em 7 países — USD, BRL, EUR, MXN, ARS, COP, CLP, PEN.
Um lojista no Brasil pode exibir preços em USD, EUR ou MXN para compradores internacionais. Uma plataforma SaaS pode mostrar o valor da assinatura na moeda local de cada cliente. Um e-commerce pode permitir que compradores troquem de moeda no checkout.
Como funciona — três passos
O fluxo de múltiplas moedas tem três passos. Você chama o endpoint de FX, exibe o preço convertido e cria a cobrança.
Passo 1 — Obter a taxa de câmbio
Chame o endpoint de FX para obter a taxa de mercado atual entre duas moedas.
Endpoint: POST /api/v1/bank/wallet/fx/rate/
Request:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
from_currency | string | Sim | Moeda de origem (ISO 4217). Exemplo: USD |
to_currency | string | Sim | Moeda de destino (ISO 4217). Exemplo: BRL |
Response:
| Campo | Tipo | Descrição |
|---|---|---|
price | float | A taxa de câmbio, arredondada para 2 casas decimais. Ao converter para moedas sem decimais (CLP, COP), arredonde o valor final para inteiro |
- cURL
- Python
- JavaScript
curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/fx/rate/' \
-H 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
-H 'Content-Type: application/json' \
-d '{
"from_currency": "USD",
"to_currency": "BRL"
}'
import requests
url = "https://core-manager.a55.tech/api/v1/bank/wallet/fx/rate/"
headers = {
"Authorization": "Bearer SEU_TOKEN_DE_ACESSO",
"Content-Type": "application/json",
}
payload = {
"from_currency": "USD",
"to_currency": "BRL",
}
response = requests.post(url, json=payload, headers=headers)
taxa = response.json()["price"]
print(f"1 USD = {taxa} BRL")
const response = await fetch(
"https://core-manager.a55.tech/api/v1/bank/wallet/fx/rate/",
{
method: "POST",
headers: {
"Authorization": "Bearer SEU_TOKEN_DE_ACESSO",
"Content-Type": "application/json",
},
body: JSON.stringify({
from_currency: "USD",
to_currency: "BRL",
}),
}
);
const { price: taxa } = await response.json();
console.log(`1 USD = ${taxa} BRL`);
Response:
{
"price": 5.73
}
Isso significa 1 USD = 5,73 BRL neste momento.
Passo 2 — Exibir o preço convertido para seu cliente
Use a taxa para mostrar ao cliente o preço na moeda dele. Isso acontece na sua aplicação — nenhuma chamada à API da A55 é necessária.
Exemplo (BRL — 2 decimais): Seu produto custa US$ 100,00. A taxa é 5,73.
Preço em BRL = US$ 100,00 × 5,73 = R$ 573,00
| O que o cliente vê | Valor |
|---|---|
| Preço do produto | US$ 100,00 |
| Taxa de câmbio | 1 USD = 5,73 BRL |
| Valor a pagar | R$ 573,00 |
Exemplo (CLP — sem decimais): Seu produto custa US$ 100,00. A taxa é 950,73.
Preço em CLP = US$ 100,00 × 950,73 = CLP 95.073 (arredonde para inteiro)
| O que o cliente vê | Valor |
|---|---|
| Preço do produto | US$ 100,00 |
| Taxa de câmbio | 1 USD = 950,73 CLP |
| Valor a pagar | CLP $95.073 |
Para moedas sem decimais, o valor enviado na cobrança deve ser um inteiro. 95073, não 95073.00. O backend trunca casas decimais para CLP e COP.
Exiba o preço original E o preço convertido. Isso gera confiança. Seu cliente sabe a taxa exata e o valor exato que o cartão ou conta bancária dele será cobrado.
Passo 3 — Criar a cobrança
Crie a cobrança na moeda de liquidação (a moeda da carteira). O valor da cobrança é o valor convertido no Passo 2.
curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/charge/' \
-H 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
-H 'Content-Type: application/json' \
-d '{
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "Maria Silva",
"payer_email": "maria@exemplo.com.br",
"payer_tax_id": "123.456.789-09",
"payer_cell_phone": "+5511978663027",
"installment_value": 573.00,
"currency": "BRL",
"due_date": "2026-04-30",
"description": "Pedido #12345 (US$ 100,00 a 5,73)",
"type_charge": "credit_card",
"installment_count": 1,
"payer_address": {
"street": "Av. Paulista",
"address_number": "1000",
"complement": "Sala 101",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310-100",
"country": "BR"
}
}'
A resposta da cobrança inclui conversão automática em múltiplas moedas:
{
"charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"local_currency": 573.00,
"currency": "BRL",
"usd_currency": 100.00,
"eur_currency": 91.45,
"type": "credit_card",
"status": "confirmed",
"installment_count": 1,
"installments": [
{
"local_currency": 573.00,
"currency": "BRL",
"usd_currency": 100.00,
"eur_currency": 91.45,
"due_date": "2026-04-30",
"status": "confirmed",
"installment_number": 1
}
]
}
Cada resposta de cobrança inclui três valores de moeda:
| Campo | Descrição | Exemplo |
|---|---|---|
local_currency | Valor na moeda de liquidação da carteira | 573,00 (BRL) |
usd_currency | Valor equivalente em dólares americanos | 100,00 (USD) |
eur_currency | Valor equivalente em euros | 91,45 (EUR) |
Você pode usar esses valores para relatórios, reconciliação e dashboards de analytics em múltiplas moedas sem chamar o endpoint de FX novamente.
Exemplo de integração completo
Este exemplo mostra o fluxo completo — autenticar, obter a taxa de câmbio, calcular o preço e criar a cobrança.
- Python
- JavaScript
import requests
BASE = "https://core-manager.a55.tech/api/v1"
AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"
# Autenticar
token_resp = requests.post(AUTH_URL, data={
"grant_type": "client_credentials",
"client_id": "SEU_CLIENT_ID",
"client_secret": "SEU_CLIENT_SECRET",
}, headers={"Content-Type": "application/x-www-form-urlencoded"})
token = token_resp.json()["access_token"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# Passo 1: Obter a taxa de câmbio
fx_resp = requests.post(f"{BASE}/bank/wallet/fx/rate/", json={
"from_currency": "USD",
"to_currency": "BRL",
}, headers=headers)
taxa = fx_resp.json()["price"]
print(f"Taxa de câmbio: 1 USD = {taxa} BRL")
# Passo 2: Calcular o preço convertido
preco_usd = 100.00
MOEDAS_SEM_DECIMAIS = {"CLP", "COP"}
moeda_destino = "BRL"
if moeda_destino in MOEDAS_SEM_DECIMAIS:
valor_cobranca = round(preco_usd * taxa)
else:
valor_cobranca = round(preco_usd * taxa, 2)
print(f"Valor da cobrança: {valor_cobranca}")
# Passo 3: Criar a cobrança em BRL
charge_resp = requests.post(f"{BASE}/bank/wallet/charge/", json={
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "Maria Silva",
"payer_email": "maria@exemplo.com.br",
"payer_tax_id": "123.456.789-09",
"payer_cell_phone": "+5511978663027",
"installment_value": valor_cobranca,
"currency": "BRL",
"due_date": "2026-04-30",
"description": f"Pedido #12345 (US$ {preco_usd} a {taxa})",
"type_charge": "credit_card",
"payer_address": {
"street": "Av. Paulista", "address_number": "1000",
"complement": "Sala 101", "neighborhood": "Bela Vista",
"city": "São Paulo", "state": "SP",
"postal_code": "01310-100", "country": "BR",
},
}, headers=headers)
cobranca = charge_resp.json()
print(f"UUID da cobrança: {cobranca['charge_uuid']}")
print(f"Local (BRL): R$ {cobranca['local_currency']}")
print(f"USD: US$ {cobranca['usd_currency']}")
print(f"EUR: € {cobranca['eur_currency']}")
const BASE = "https://core-manager.a55.tech/api/v1";
const AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token";
// Autenticar
const tokenResp = await fetch(AUTH_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "client_credentials",
client_id: "SEU_CLIENT_ID",
client_secret: "SEU_CLIENT_SECRET",
}),
});
const { access_token } = await tokenResp.json();
const headers = {
Authorization: `Bearer ${access_token}`,
"Content-Type": "application/json",
};
// Passo 1: Obter a taxa de câmbio
const fxResp = await fetch(`${BASE}/bank/wallet/fx/rate/`, {
method: "POST",
headers,
body: JSON.stringify({ from_currency: "USD", to_currency: "BRL" }),
});
const { price: taxa } = await fxResp.json();
console.log(`Taxa de câmbio: 1 USD = ${taxa} BRL`);
// Passo 2: Calcular o preço convertido
const precoUsd = 100.0;
const MOEDAS_SEM_DECIMAIS = new Set(["CLP", "COP"]);
const moedaDestino = "BRL";
const valorCobranca = MOEDAS_SEM_DECIMAIS.has(moedaDestino)
? Math.round(precoUsd * taxa)
: Math.round(precoUsd * taxa * 100) / 100;
console.log(`Valor da cobrança: ${valorCobranca}`);
// Passo 3: Criar a cobrança em BRL
const chargeResp = await fetch(`${BASE}/bank/wallet/charge/`, {
method: "POST",
headers,
body: JSON.stringify({
wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
merchant_id: "11111111-1111-1111-1111-111111111111",
payer_name: "Maria Silva",
payer_email: "maria@exemplo.com.br",
payer_tax_id: "123.456.789-09",
payer_cell_phone: "+5511978663027",
installment_value: valorCobranca,
currency: "BRL",
due_date: "2026-04-30",
description: `Pedido #12345 (US$ ${precoUsd} a ${taxa})`,
type_charge: "credit_card",
payer_address: {
street: "Av. Paulista", address_number: "1000",
complement: "Sala 101", neighborhood: "Bela Vista",
city: "São Paulo", state: "SP",
postal_code: "01310-100", country: "BR",
},
}),
});
const cobranca = await chargeResp.json();
console.log(`UUID da cobrança: ${cobranca.charge_uuid}`);
console.log(`Local (BRL): R$ ${cobranca.local_currency}`);
console.log(`USD: US$ ${cobranca.usd_currency}`);
console.log(`EUR: € ${cobranca.eur_currency}`);
Moedas suportadas
A API de FX suporta 8 moedas em 7 países LATAM mais USD e EUR, totalizando 56 pares de conversão.
| Código | Moeda | País / Região | Decimais | Carteira suportada |
|---|---|---|---|---|
USD | Dólar Americano | Estados Unidos | 2 | — |
BRL | Real Brasileiro | Brasil | 2 | Sim |
EUR | Euro | Zona do Euro | 2 | — |
MXN | Peso Mexicano | México | 2 | Sim |
ARS | Peso Argentino | Argentina | 2 | Sim |
COP | Peso Colombiano | Colômbia | 0 | — |
CLP | Peso Chileno | Chile | 0 | Sim |
PEN | Sol Peruano | Peru | 2 | — |
Ao converter para CLP ou COP, o valor final da cobrança deve ser um inteiro. Após multiplicar pela taxa FX, arredonde para o número inteiro mais próximo com round(). Exemplo: USD 100.00 × 950.73 = CLP 95.073 (não 95073.00).
Principais corredores de câmbio
| Par | Caso de uso |
|---|---|
| USD → BRL | Empresas americanas vendendo para clientes brasileiros |
| USD → MXN | Empresas americanas vendendo para clientes mexicanos |
| EUR → BRL | Empresas europeias entrando no Brasil |
| BRL → USD | SaaS brasileiro, exportações, remessas |
| USD → CLP | Empresas americanas vendendo para clientes chilenos |
| USD → ARS | Empresas americanas vendendo para clientes argentinos |
| USD → COP | Empresas americanas vendendo para clientes colombianos |
| USD → PEN | Empresas americanas vendendo para clientes peruanos |
Fonte e atualização da taxa
| Propriedade | Valor |
|---|---|
| Fonte da taxa | Taxa de mercado interbancário (mid-market) |
| Fórmula | (Bid + Ask) / 2 — sem markup de nenhuma instituição |
| Janela de cache | ~17 minutos (1.000 segundos) |
| Disponibilidade | Fallback em cascata entre múltiplas fontes de dados |
| Arredondamento | 2 casas decimais para a taxa; valor final da cobrança segue os decimais da moeda (0 para CLP/COP, 2 para as demais) |
| Horário de mercado | 24/5 — segunda a sexta |
| Fim de semana | Retorna a taxa de fechamento de sexta-feira (Nova York, 17h EST) |
A taxa mid-market é o ponto médio entre o preço de compra e venda no mercado interbancário. Ela não tem nenhum markup. Bancos centrais, reguladores e fintechs a usam como a referência mais justa para conversão de moedas. O mercado Forex movimenta mais de US$ 9,6 trilhões por dia (BIS 2025) — nenhum outro mercado financeiro oferece esse nível de liquidez e precisão.
Casos de uso
| Cenário | Como usar o endpoint de FX |
|---|---|
| Checkout cross-border | Obtenha a taxa, exiba o preço convertido para o comprador antes da confirmação |
| Precificação dinâmica | Atualize os preços no seu site com base na taxa de câmbio atual |
| Dashboard multi-moeda | Converta todos os valores de transações para USD ou EUR para relatórios consolidados |
| Reconciliação financeira | Compare a taxa do momento da transação com a taxa do momento da liquidação |
| Preço de assinatura | Mostre aos assinantes o valor mensal na moeda local deles |
| Geração de faturas | Inclua a taxa de câmbio e os valores em ambas as moedas nas faturas |
Observações importantes
Para moedas com controles de capital — especialmente o Peso Argentino (ARS) — a taxa mid-market pode divergir das taxas oficiais ou paralelas praticadas localmente. A taxa retornada reflete o mercado interbancário internacional.
O endpoint de FX fornece taxas para exibição e cálculo. Ele não reserva nem trava uma taxa. A conversão efetiva aplicada à cobrança depende do adquirente e do momento da liquidação.
Armazene a taxa de câmbio que você mostrou ao cliente junto com a cobrança. Inclua no campo description da cobrança (por exemplo: "Pedido #12345 (US$ 100,00 a 5,73)"). Isso cria uma trilha de auditoria para reconciliação e resolução de disputas.