Vender em múltiplas moedas (BRL, USD e mais)

Resposta curta

O LimãoPay separa preço por idioma. Você define quanto cobra em pt-BR (R$) e em en-US (US$) e o sistema escolhe a moeda certa com base em 3 sinais, em ordem:

1. Moeda fixada no Payment Link (link.locale)
2. Idioma do buyer (?locale=en-US ou Accept-Language)
3. Idioma primário da sua loja (tenant.locale)

Cada gateway aceita um conjunto de moedas — PIX é BRL only, Mercado Pago atende América Latina, Stripe atende o mundo todo. O sistema bloqueia configurações incompatíveis (ex: cobrar USD com só PIX ativo).

Passo 1 — Habilite o idioma na loja

1. Configurações → Loja → Idiomas
2. Marque English (US) (ou outro idioma)
3. Salve

A partir daqui, o painel de edição de produto passa a mostrar campos de tradução + preço por idioma.

Passo 2 — Defina o preço em cada moeda

Abra um produto e role até Preços. Pra cada idioma habilitado:

• pt-BR: R$ 97,00
• en-US: $ 19,00

Importante: o LimãoPay não converte automaticamente. Você define explicitamente quanto cobra em cada mercado — igual Shopify Markets. Se você quer o mesmo número em ambas, digita 97 nos dois. Se quer ajustar pra mercado americano (paridade), digita 19.

Esses dois preços viram duas verdades independentes — quem acessar limaopay.com.br/sualoja/produto paga R$97, quem acessar limaopay.app/sualoja/produto paga $19.

Passo 3 — Ative o gateway certo

Cada gateway aceita um conjunto fixo de moedas:

Regra prática: pra vender em USD, ative Stripe Connect. Pra vender em BRL, qualquer um dos 3 serve.

Configure em Painel do produto → Métodos de pagamento. O LimãoPay bloqueia automaticamente combinações incompatíveis e te avisa o que falta (ex: "Pra cobrar em USD você precisa ativar Stripe").

Payment Link multi-moeda

Cada Payment Link cobra em uma moeda específica — igual Stripe Payment Links. Não tem auto-detecção. Vendedor escolhe explicitamente.

Como usar (SaaS externo enviando buyers de mercados diferentes):

1. Painel do produto → Links de pagamento → Novo link
2. Selecione a moeda do link (só aparece se o produto for multi-currency)
3. Copie o link gerado

Repita pra cada moeda — 1 link em BRL e 1 link em USD pro mesmo produto. Seu sistema decide qual mandar baseado no mercado do buyer.

Buyer brasileiro → mandar /pay/abc123 → cobra R$ 97
Buyer americano  → mandar /pay/xyz789 → cobra $ 19

Cada link guarda a moeda própria — o checkout abre exatamente naquela.

Página pública (sem Payment Link)

A página pública (/sualoja/produto) detecta automaticamente o idioma pelo domínio:

• limaopay.com.br/... → pt-BR → BRL
• limaopay.app/... → en-US → USD

Buyer pode também forçar locale via ?locale=en-US na URL. SaaS externo que enviar buyers internacionais pode usar isso pra direcionar o tráfego pro idioma correto.

Como o backend resolve a moeda (visão técnica)

Cada checkout (PIX, Mercado Pago, Stripe, chatbot Telegram, agente IA) passa pelo helper único pricingService.resolvePriceForCheckout():

const resolved = pricingService.resolvePriceForCheckout({
  offer: { prices: offer.prices, primaryLocale: offer.primaryLocale },
  localePreference: [
    paymentLink?.locale,    // 1ª prioridade
    buyerLocale,            // 2ª: do Accept-Language ou ?locale=
    tenant.locale,          // 3ª: fallback do vendedor
  ],
  productFallback: { price, currency, originalPrice }, // pré-V2
});
// → { price: 1900, currency: 'USD', resolvedLocale: 'en-US', source: 'offer.prices' }

O sistema garante 3 invariantes:

• Order é snapshot imutável — Order.amount e Order.currency viram a verdade histórica daquela venda
• Webhook respeita o snapshot — payload order.paid traz amount_total e currency do Order
• Email/notificação respeita o snapshot — cart recovery, comprovante e instruções PIX usam o valor do checkout abandonado, não o preço atual

Limites e validações automáticas

• PIX rejeita não-BRL: se você fixar locale en-US em um link PIX, o checkout bloqueia com mensagem clara orientando a usar Stripe
• Mercado Pago rejeita USD: o currency_id do MP é dinâmico, mas só processa BRL/ARS/MXN/COP/CLP/PEN/UYU
• Stripe aceita praticamente tudo: 14 moedas comuns suportadas; outras dão fallback pro idioma primário

Webhook traz a moeda correta

O payload order.paid já entrega a moeda real da transação:

{
  "type": "order.paid",
  "data": {
    "object": {
      "id": "ord_xxx",
      "amount_total": 1900,
      "currency": "usd",
      "buyer_email": "john@example.com",
      "external_customer_id": "user_42"
    }
  }
}

Seu SaaS pode liberar o Pro baseado na moeda + valor, sem precisar de polling adicional.

Checklist multi-moeda

• Habilitar idioma extra em Configurações → Loja → Idiomas
• Definir preço em cada moeda no painel do produto
• Ativar gateway compatível (Stripe pra USD/EUR/etc)
• Criar 1 Payment Link por moeda no painel do produto
• Testar checkout em cada link (modo test do Stripe ajuda)
• Validar payload do webhook com moeda correta