Stripe: cobrar em reais e em dólar no mesmo produto com currency_options
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 [email protected], 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.completeddispara quando o checkout termina, não quando o dinheiro entra. A doc de fulfillment, conferida em 25/08/2026, manda verificar opayment_statusda Session antes de entregar. E manda ouvir tambémcheckout.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 aopayment_status. Uma sessãounpaidé reconhecida e fica dormente até o sucesso assíncrono. Ou até oasync_payment_failedenterrá-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.deleteddo 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
- 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).
- Um Price, várias moedas:
currency_optionsno 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ê. - “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.
- Cote server-side, na moeda que o cartão vai pagar:
CF-IPCountryna borda, USD como fallback seguro. Mantenha a resposta fora de cache compartilhado, e deixe o idioma para outro sinal. - Duas idempotências, porque são dois problemas: atribuição absoluta + marca-d’água de
createdpara 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. - Entregue depois do dinheiro: gate em
payment_status, fulfillment compartilhado entrecompletedeasync_payment_succeeded. Um método de confirmação demorada não ganha nada no “completed”. - 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 →