Operações Multi-moeda
Quick Reference
O problema — por que conversão de moeda causa chargebacks
Quando um lojista liquida apenas em BRL, portadores de cartão internacionais (EUR/USD) passam por uma cadeia de conversão: taxa A55 → taxa da rede de cartão → markup do emissor. Cada camada adiciona custo. Se a taxa varia entre o momento da cotação e a liquidação, a fatura do portador mostra um valor maior do que o esperado — disparando o código Mastercard 4834 ("Valor da transação diverge").
A causa raiz não é a taxa de câmbio em si. É a diferença entre a taxa mostrada ao cliente e a taxa que o banco emissor aplica na fatura.
Três estratégias resolvem esse problema, cada uma com trade-offs diferentes.
Opção A — Carteira EUR/USD nativa (recomendada)
Elimine a cadeia de conversão por completo. Configure uma carteira em EUR ou USD. As cobranças são liquidadas nativamente na moeda do portador. O banco emissor vê uma transação em moeda local — sem markup cross-border, sem variação cambial, sem chargebacks 4834.
Como funciona
Configuração
- Solicite uma carteira EUR ou USD ao seu gerente de conta A55.
- Use o UUID da carteira ao criar cobranças.
- Defina
currencycomoEURouUSDna requisição.
Exemplo
- cURL
- Python
curl -X POST 'https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/' \
-H 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
-H 'Content-Type: application/json' \
-d '{
"wallet_uuid": "SEU_UUID_CARTEIRA_EUR",
"merchant_id": "SEU_MERCHANT_ID",
"payer_name": "Maria Silva",
"payer_email": "maria@exemplo.com.br",
"installment_value": 100.00,
"currency": "EUR",
"due_date": "2026-04-30",
"description": "Pedido #12345",
"type_charge": "credit_card",
"installment_count": 1
}'
import requests
BASE = "https://sandbox.api.a55.tech/api/v1"
headers = {
"Authorization": "Bearer SEU_TOKEN_DE_ACESSO",
"Content-Type": "application/json",
}
charge_resp = requests.post(f"{BASE}/bank/wallet/charge/", json={
"wallet_uuid": "SEU_UUID_CARTEIRA_EUR",
"merchant_id": "SEU_MERCHANT_ID",
"payer_name": "Maria Silva",
"payer_email": "maria@exemplo.com.br",
"installment_value": 100.00,
"currency": "EUR",
"due_date": "2026-04-30",
"description": "Pedido #12345",
"type_charge": "credit_card",
"installment_count": 1,
}, headers=headers)
cobranca = charge_resp.json()
print(f"UUID da cobrança: {cobranca['charge_uuid']}")
print(f"Valor: €{cobranca['local_currency']}")
Por que esta é a melhor opção
| Fator | Carteira EUR/USD nativa | Carteira BRL com conversão FX |
|---|---|---|
| Cadeia de conversão | Nenhuma — cobrança e liquidação na mesma moeda | Taxa A55 → taxa da rede → markup do emissor |
| Risco de chargeback (4834) | Zero | Baixo com taxas atualizadas, alto com taxas defasadas |
| Fatura do portador | Valor exato mostrado no checkout | Pode diferir 1,6–4,4% por taxas bancárias |
| Chamadas à API de FX | Nenhuma | Sim — obter taxa antes de cada cobrança |
| Complexidade de integração | Igual a qualquer cobrança — apenas defina currency: "EUR" | Lógica FX adicional, cache, reobtém na confirmação |
Para habilitar uma carteira EUR ou USD, entre em contato com seu gerente de conta A55. A criação da carteira geralmente leva 1–2 dias úteis.
Opção B — Conversão via API FX
Se sua moeda de liquidação é BRL mas seus clientes pagam em EUR ou USD, use a API de FX da A55 para obter taxas mid-market em tempo real, exibir o preço convertido e criar a cobrança em BRL.
Essa abordagem funciona bem quando combinada com boas práticas (reobtém a taxa na confirmação, divulgação transparente). O banco emissor do portador ainda pode adicionar 1–3% de taxa de transação internacional — isso é padrão nas redes Visa e Mastercard e raramente gera disputas.
Para o guia completo da API FX, veja Taxas de Câmbio.
Pontos-chave
- Taxas mid-market sem markup da A55 — 8 moedas, 56 pares.
- Cache de ~17 minutos — reobtém a taxa no momento da confirmação do pagamento para minimizar variação.
- Registre a taxa no campo
descriptionda cobrança para auditoria e defesa de disputas. - Risco de markup do emissor: mesmo com taxa perfeita, o banco do portador adiciona 1–3% sobre mid-market. Isso está descrito no contrato do portador com o banco e raramente causa disputas. O risco crítico são taxas defasadas criando grandes discrepâncias.
Quando usar a Opção B
- Sua infraestrutura atual liquida em BRL e a migração para carteira EUR/USD não é imediata.
- Você atende clientes em múltiplas moedas além de EUR/USD (MXN, ARS, CLP, COP, PEN).
- Você quer exibir preços na moeda do cliente mantendo a liquidação em BRL.
Opção C — Diversificação multi-moeda estratégica
Combine as Opções A e B. Use carteiras EUR/USD nativas para seus principais mercados internacionais e a API FX para outras moedas. Essa abordagem transforma o problema de chargeback em vantagem competitiva.
Por que aprender cotação FX
O BRL é uma das moedas mais líquidas da América Latina. Mas se você expandir para México (MXN), Chile (CLP), Colômbia (COP), Peru (PEN) ou Argentina (ARS), cada moeda terá sua própria dinâmica de conversão. Aprender a gerenciar cotação FX agora — enquanto resolve o problema de chargeback EUR/USD — prepara sua plataforma para operações multi-país.
Arquitetura recomendada
Passos de implementação
- Imediatamente: solicite carteiras EUR e USD — elimina chargebacks para seus principais clientes internacionais.
- Em paralelo: integre a API FX para liquidação em BRL ao atender clientes LATAM.
- Gradualmente: conforme você adiciona clientes MXN, CLP ou COP, a infraestrutura de cotação FX já estará pronta.
Comparação
| Opção A: EUR/USD nativa | Opção B: API FX | Opção C: Diversificação | |
|---|---|---|---|
| Risco de chargeback | Zero | Baixo (com taxas atualizadas) | Zero para EUR/USD, baixo para outras |
| Esforço de integração | Mínimo — mesma API de cobrança | Moderado — lógica FX + reobtém taxa | Ambos combinados |
| Custo de conversão | Nenhum — sem conversão | Taxa FX 1,0–2,5% na liquidação | Nenhum para EUR/USD, taxa FX para outras |
| Escalabilidade | Apenas EUR/USD | Qualquer das 8 moedas suportadas | Plataforma multi-moeda completa |
| Tempo de implementação | 1–2 dias úteis (criação da carteira) | Já disponível | Rollout em fases |
| Melhor para | Lojistas com clientes EUR/USD | Precificação multi-moeda LATAM | Plataformas globais com base diversa |
Recomendações de boas práticas
- Comece pela Opção A se seus clientes pagam principalmente em EUR ou USD. Ela elimina a causa raiz dos chargebacks com zero esforço de integração.
- Adicione a Opção B quando precisar atender clientes em outras moedas (MXN, CLP, COP, PEN, ARS).
- Sempre reobtém a taxa no momento da confirmação do pagamento ao usar a API FX. Veja Taxas de Câmbio.
- Exiba ambas as moedas no checkout — o preço original e o valor convertido — independentemente da opção escolhida.
- Registre tudo — valor da taxa, timestamp da consulta, valor exibido, valor cobrado — para reconciliação e defesa de disputas.