Pular para o conteúdo
stripebillingpagamentosbrasilsaaswebhook

Stripe: cobrar em reais e em dólar no mesmo produto com currency_options

Douglas Haruo 12 min 21/09/2026

Para cobrar o mesmo produto em dólar e em real no Stripe, o desenho certo é um único Price com um valor adicional em currency_options. Nunca um segundo Price por moeda: cada Price novo nasce com um price_... id novo, e todo o seu backend mapeia plano por esse price id. O Checkout apresenta a moeda local do comprador sozinho (documentação de multi-currency prices, conferida em 25/08/2026). O que sobra para você são as três partes que a doc não escreve. Primeira: cotar a moeda certa antes do checkout, aqui lendo o país que a Cloudflare anota no header CF-IPCountry. Segunda: entender por que uma conta Stripe Brasil precisa das duas moedas. Terceira: dar ao webhook, o endereço que recebe os avisos do Stripe, as duas idempotências que ele precisa. Elas são as guardas contra evento repetido e evento fora de ordem, e não são a mesma.

Este post é o caso real do Tamperlens, que cobra em USD e BRL desde o terceiro dia de vida. A história de como o billing chegou a produção está no post 30 dias do primeiro commit ao Stripe live. Aqui é a mecânica: o que configurar, o que codificar, e as pegadinhas que custaram sessões de debugging de verdade. Os valores dos planos não importam para nada disso e ficam onde sempre estiveram: na página de preços.


Por que uma conta Stripe Brasil precisa das duas moedas?

Porque a restrição regulatória corta o problema ao meio. A página de suporte do Stripe sobre transações recusadas em contas Stripe Brasil foi conferida em 25/08/2026. Ela diz que “transações de pagamento cross-border e atividades de câmbio (FX) são restritas para contas de merchant no Stripe Brasil”. E abre uma exceção exata, que vale citar no original: “The restriction does not apply to Visa and Mastercard international card transactions where the issuer is outside Brazil and the merchant is a Stripe Brazil account.”

Na prática, para um SaaS operando numa conta Stripe Brasil que vende para o mundo:

  • Cartão emitido no Brasil → cobrado em reais. Envolver esse cartão numa cobrança em moeda estrangeira é exatamente a atividade de câmbio que a restrição recusa.
  • Cartão Visa/Mastercard emitido fora → pode ser cobrado em dólar (ou outra moeda), pela exceção acima.

Ou seja: não dá para escolher “só dólar” nem “só real” sem abrir mão de metade dos compradores. O produto precisa das duas moedas no mesmo plano. É aí que a maioria das integrações erra a primeira decisão.

Como funciona um Price multi-moeda (currency_options)?

Um Price do Stripe tem uma moeda padrão e pode carregar valores adicionais por moeda em currency_options: um objeto só, um id só. Pela API:

curl https://api.stripe.com/v1/prices \
  -u "$STRIPE_SECRET_KEY:" \
  -d currency=usd \
  -d unit_amount=1000 \
  -d "currency_options[brl][unit_amount]=5000" \
  -d "product_data[name]=Meu Plano"

O Checkout recebe o mesmo price id de sempre em line_items e resolve a moeda sozinho. A doc diz: “quando você usa Prices multi-moeda numa Session, o Checkout lida automaticamente com a localização de moeda para os seus clientes”. Você pode forçar uma moeda específica passando currency na criação da Session, se quiser tirar a decisão da localização (mesma doc, conferida em 25/08/2026).

Três decisões que a doc deixa com você:

O valor em real é definido à mão, e isso é uma feature. O caminho de currency_options que o Stripe chama de manual currency prices não converte nada: você declara o valor de cada moeda e ele fica estático. O risco cambial é seu. A alternativa recomendada pela doc, o Adaptive Pricing, converte automaticamente pela taxa do dia.

Para um SaaS, o valor manual costuma ser a escolha certa por uma razão que não é técnica: preço em moeda local é decisão de posicionamento, não de cotação. Um plano que muda de preço em real toda semana conforme o câmbio não é um preço, é um índice. No Tamperlens, o valor em BRL de cada Price é definido à mão no dashboard e nunca foi uma conversão do valor em dólar.

Os dois números precisam morar num lugar só do seu código. Se o backend mostra preços, numa página de pricing ou num dashboard, os valores USD e BRL que ele exibe têm que bater com os que estão nos Price objects. Nada no Stripe verifica isso por você. A resposta da casa é um módulo único com a escada de planos inteira. Um teste deriva a página pública desse módulo, para que os dois não possam divergir sem quebrar o CI, a bateria de testes automáticos. O desenho desse teste tem post próprio.

Dá para testar a moeda sem VPN. Para simular um comprador de outro país no Checkout, a doc oficial tem um truque de teste. Você passa um e-mail com sufixo de localização, como test+location_BR@example.com, no campo customer_email da Session. A página apresenta a mesma moeda que um comprador daquele país veria.

Por que “Add another price” quebra o mapeamento?

Essa é a pegadinha que custou uma sessão de debugging na casa em 27/07/2026, e ela mora numa ambiguidade do dashboard. Num produto do catálogo existem dois botões parecidos:

  • “+ Add another price”: cria um Price novo, com um price_... id novo.
  • “+ Add a price by currency” (dentro do Price existente): adiciona uma moeda ao mesmo Price, mesmo id.

A diferença parece cosmética e é estrutural. Todo backend de billing sério mapeia price id → plano. No Tamperlens essa função tem até nome, planForPriceId(), e devolve null para qualquer id que não reconhece. Um id desconhecido nunca pode virar upgrade.

Agora siga a cadeia do botão errado. Você “adiciona o preço em real” criando um segundo Price, e o comprador brasileiro paga por ele. O webhook chega com um price id que o app não mapeia. O handler responde 200, porque não há o que retentar, e não aplica plano nenhum. A compra completa, o dinheiro entra, e a conta continua no plano free. Nenhum log parece errado: o Stripe mostra entrega 2xx, o app registrou “id desconhecido, ignorado”, e o cliente pagante abre um ticket.

A regra que ficou gravada na documentação de operação da casa: moeda nova se adiciona ao Price existente; Price novo só quando existe um plano novo. E quando um Price novo é inevitável (um reprice de verdade), a variável de ambiente que aponta o id precisa ser atualizada no mesmo ato. Um id órfão de um lado ou do outro produz o mesmo cliente invisível.

Como cotar a moeda certa antes do checkout?

O Checkout resolve a moeda na hora de pagar. Mas a sua página de preços fala antes dele. Uma página que diz $ para quem vai ser cobrado em R$ quebrou a única promessa que uma página de preços tem. Cotação e cobrança precisam ser o mesmo número.

A solução do Tamperlens é cotar server-side, no próprio servidor, pela geografia da requisição. Toda requisição que passa pela borda da Cloudflare chega ao origin, o servidor de origem, com o país do visitante anotado no header CF-IPCountry. Como a caixa não tem porta aberta e só é alcançável através do túnel da Cloudflare, esse cabeçalho vem sempre da borda, não do cliente. O endpoint público de pricing, a rota que a página de preços consulta, lê o header e responde a escada inteira na moeda certa:

const country = String(request.headers["cf-ipcountry"] ?? "").trim().toUpperCase();
const currency = country === "BR" ? "BRL" : "USD";

Três decisões finas nesse endpoint, todas deliberadas:

  • Header ausente cai em USD. Uma requisição sem CF-IPCountry (dev local, probe direto) é cotada em dólar. É a direção segura: USD é a moeda padrão dos Price objects e o que qualquer cartão não-brasileiro paga.
  • A resposta não entra em cache compartilhado. São três números, mas são os números daquele visitante. Um CDN, esse cache compartilhado da rede, servindo a resposta do Brasil para um visitante dos EUA é exatamente o bug que o endpoint existe para impedir. Cache-Control: no-store, private.
  • País decide moeda; idioma é outro sinal. Um brasileiro em Lisboa lê a página em português e vê o preço na moeda que o cartão dele vai pagar dali. Misturar os dois sinais é como se produz a página que cota numa moeda e cobra em outra.

Por que o webhook precisa de duas idempotências?

A doc de webhooks do Stripe, conferida em 25/08/2026, estabelece duas realidades que todo handler de billing, o código que recebe esses eventos, tem que engolir. A primeira: “a Stripe não garante a entrega dos eventos na ordem em que foram gerados”. A segunda: “ocasionalmente, os endpoints de webhook podem receber o mesmo evento mais de uma vez”, com retries automáticos por até três dias. Ou seja: replay e desordem, evento repetido e evento fora de ordem, não são edge cases: são o contrato.

O que quase ninguém escreve é que replay e desordem são problemas diferentes. A proteção certa depende do tipo de efeito que o evento produz. No Tamperlens são dois tipos, e cada um ganhou a sua idempotência:

Mudança de plano é atribuição absoluta → marca-d’água. “Esta conta agora está no plano X” é um efeito que converge: aplicar duas vezes dá o mesmo resultado, então replay é inofensivo de graça. O problema restante é a ordem.

A sequência que custa dinheiro é banal. O evento do plano menor falha na entrega. O evento do plano maior chega e é aplicado. Minutos depois, o retry do evento antigo chega e rebaixa a conta que acabou de pagar pelo upgrade. Há um 200 ao lado de cada entrega e nenhum log parecendo errado.

A guarda é uma marca-d’água por conta: o created do último evento aplicado fica gravado, e um evento mais antigo que ela é reconhecido com 200 e descartado. Responder erro faria o Stripe retentar para sempre um evento que já perdeu a vez. Detalhe fino: a comparação é estritamente <, não <=. O campo created tem resolução de um segundo, e uma compra real emite dois eventos dentro do mesmo segundo; rejeitar o segundo seria regressão, não guarda.

Crédito é delta → PRIMARY KEY. Um pacote pré-pago é saldo += N, e isso não converge em nada. A marca-d’água não serve em nenhuma direção. Um replay carrega o mesmo created do original, então created < última é falso e o pacote seria concedido de novo. A marca-d’água ordena eventos, mas não os identifica: são problemas diferentes. E consultá-la descartaria compras legítimas, porque uma compra de crédito não é ordenada contra um evento de assinatura. São transações sem relação.

A proteção certa é de identidade: uma tabela de concessões com PRIMARY KEY no id da Checkout Session, uma chave que recusa duas linhas com o mesmo id. O replay vira um INSERT que conflita, e a resposta é 200 sem conceder de novo. Identidade para o problema de identidade, ordem para o problema de ordem.

Duas guardas vizinhas que completam o handler:

  • O dinheiro antes do efeito. Para métodos de pagamento com confirmação demorada, o checkout.session.completed dispara quando o checkout termina, não quando o dinheiro entra. A doc de fulfillment, conferida em 25/08/2026, manda verificar o payment_status da Session antes de entregar. E manda ouvir também checkout.session.async_payment_succeeded, que só dispara quando o pagamento assíncrono confirma. O handler da casa passa os dois eventos pela mesma função de fulfillment, a entrega do que foi comprado, condicionada ao payment_status. Uma sessão unpaid é reconhecida e fica dormente até o sucesso assíncrono. Ou até o async_payment_failed enterrá-la de vez, sem nada para revogar porque nada foi concedido.
  • De quem é essa assinatura? Se mais de um produto fatura pela mesma conta Stripe, o seu endpoint recebe os eventos de todos. Um customer.subscription.deleted do produto vizinho, agindo só sobre status e customer, rebaixaria um cliente pagante seu. O caminho de downgrade confere se a assinatura cancelada é a que sustenta o plano. A checagem é pelo id gravado na compra ou, para contas antigas, por o preço ser um que você vende. O caminho de upgrade já era seguro por construção, porque deriva o plano do price id.

Quais são as três pegadinhas que custaram tempo de verdade?

Estão documentadas no repositório com este título exato: “três pegadinhas que custaram tempo real, gravadas para nunca serem revividas”.

1. A URL do endpoint de webhook tem que ser exata. Não “o domínio certo”, e sim a URL exata, caractere por caractere. A razão está na doc de webhooks: o Stripe considera respostas de redirecionamento como falhas de entrega. Uma URL registrada que responde 301 não é “quase certa”. Pode ser um www que redireciona para o domínio raiz (o apex), um path antigo ou um trailing slash normalizado. Em qualquer desses casos, é um endpoint que falha 100% das entregas enquanto o site parece perfeito no navegador, que segue redirects sem contar.

2. “Add another price” cria um price id novo. A seção acima inteira. Vale repetir em uma linha: moeda se adiciona ao Price existente; um id que o app não mapeia é uma compra que completa sem efeito.

3. O bloco environment do compose é uma whitelist. Um deploy com docker compose que declara variáveis explicitamente no environment: do serviço não repassa o que não está declarado. É uma lista de permissão: uma variável nova no .env da caixa não existe para o processo até ser nomeada lá também. É assim que um price id novo pode estar presente no servidor e invisível para o app. O plano responde “não configurado”, todo o resto funciona, e o grep no .env jura que está tudo lá. A casa fechou essa com um teste que falha se a variável de um plano pago faltar no compose. É a mesma filosofia do teste que deriva o número publicado: o que pode divergir em silêncio, um teste amarra.

E uma quarta, de código, que merece registro porque foi paga na primeira compra live: o payload do webhook não é o objeto do SDK. Uma Checkout Session recuperada pela API pode carregar line_items expandido. A mesma session chegando num webhook não carrega. O handler lia o plano de uma lista de ids escrita à mão, com fallback em line_items, e deixou um cliente pagante no plano free. A compra caiu num branch que payloads de webhook nunca populam. As correções viraram regra. O plano viaja em metadata definida na criação do checkout. E pertencimento a um conjunto se pergunta a um predicado único (isPaidPlanId()), nunca a uma lista redigitada em cada ponto de uso.

O resumo que você leva

  1. Uma conta Stripe Brasil vive de duas moedas: FX é restrito para o merchant Brasil, com exceção para Visa/Mastercard emitidos fora. Cartão BR paga em reais, cartão de fora paga em dólar (suporte oficial, conferido em 25/08/2026).
  2. Um Price, várias moedas: currency_options no mesmo objeto, mesmo id (doc). O valor em cada moeda é decisão de posicionamento, definida à mão. E é amarrada ao código por teste, porque nada no Stripe confere por você.
  3. “Add a price by currency”, nunca “Add another price”: um price id que o backend não mapeia é uma compra que completa e não entrega nada. O cliente pagante fica no free com 200 em todos os logs.
  4. Cote server-side, na moeda que o cartão vai pagar: CF-IPCountry na borda, USD como fallback seguro. Mantenha a resposta fora de cache compartilhado, e deixe o idioma para outro sinal.
  5. Duas idempotências, porque são dois problemas: atribuição absoluta + marca-d’água de created para mudanças de plano (desordem); PRIMARY KEY no id da Checkout Session para créditos (replay). A marca-d’água não identifica eventos e a chave não os ordena. Não tente usar uma no lugar da outra.
  6. Entregue depois do dinheiro: gate em payment_status, fulfillment compartilhado entre completed e async_payment_succeeded. Um método de confirmação demorada não ganha nada no “completed”.
  7. As três pegadinhas de operação: URL de webhook exata (redirect conta como falha), moeda ≠ price novo, e o environment: do compose como whitelist. Cada uma silenciosa, cada uma com cara de “está tudo verde”.

Precisa de um projeto técnico sob medida?

Arquitetura, TypeScript, APIs e automação, do protótipo à produção. Quem responde o seu e-mail é quem escreve o código, e o prazo que eu prometo é o prazo que eu consigo cumprir.

Me manda uma mensagem →