Stripe: Charging USD and BRL on the Same Product with currency_options
To charge the same product in dollars and in reais on Stripe, the right design is a single Price carrying an extra amount in currency_options. Never a second Price per currency: every new Price is born with a new price_... id, and your entire backend maps plans by that price id. Checkout presents the buyer’s local currency on its own (multi-currency prices documentation, checked 2026-08-25). What’s left for you are the three parts the doc doesn’t write. First: quoting the right currency before checkout, here by reading the country Cloudflare stamps in the CF-IPCountry header. Second: understanding why a Stripe Brazil account needs both currencies at all. Third: giving the webhook, the address that receives Stripe’s notifications, the two idempotency mechanisms it needs. They are the guards against a repeated event and an out-of-order event, and they are not the same one.
This post is the real case of Tamperlens, which has billed in USD and BRL since its third day alive. The story of how billing reached production is in thirty days from first commit to Stripe live. This is the mechanics: what to configure, what to code, and the gotchas that cost real debugging sessions. The plan amounts matter for none of it and stay where they’ve always been: on the pricing page.
Why does a Stripe Brazil account need both currencies?
Because the regulatory restriction cuts the problem in half. Stripe’s support page on declined transactions for Stripe Brazil accounts was checked on 2026-08-25. It states that “cross-border payment transactions and foreign exchange (FX) activities are restricted for merchant accounts in Stripe Brazil”. And it carves one exact exception: “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.”
In practice, for a SaaS on a Stripe Brazil account selling to the world:
- A card issued in Brazil → charged in reais. Pulling that card into a foreign-currency charge is precisely the FX activity the restriction declines.
- A Visa/Mastercard issued abroad → can be charged in dollars (or another currency), through the exception above.
Which means: you can’t pick “USD only” or “BRL only” without giving up half your buyers. The product needs both currencies on the same plan. That’s where most integrations get the first decision wrong.
How does a multi-currency Price (currency_options) work?
A Stripe Price has a default currency and can carry additional per-currency amounts in currency_options: one object, one id. Through the 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]=My Plan"
Checkout receives the same price id as always in line_items and resolves the currency itself. The doc says: “when you use multi-currency Prices in a Session, Checkout automatically handles currency localization for your customers”. You can force a specific currency by passing currency when creating the Session, if you want to take the decision away from geolocation (same doc, checked 2026-08-25).
Three decisions the doc leaves with you:
The BRL amount is set by hand, and that’s a feature. The currency_options path Stripe calls manual currency prices converts nothing: you declare each currency’s amount and it stays static. The FX risk is yours. The doc’s recommended alternative, Adaptive Pricing, converts automatically at the day’s rate.
For a SaaS, the manual amount is usually the right call for a reason that isn’t technical: a local-currency price is a positioning decision, not an exchange-rate lookup. A plan whose BRL price shifts weekly with the market isn’t a price, it’s an index. In Tamperlens, the BRL amount on each Price is set by hand in the dashboard and has never been a conversion of the USD figure.
Both numbers need to live in exactly one place in your code. If your backend displays prices, on a pricing page or a dashboard, the USD and BRL amounts it shows have to match the ones on the Price objects. Nothing in Stripe checks that for you. The house answer is a single module holding the entire plan ladder. A test then derives the public page from that module, so the two cannot drift without breaking CI, the automated test run. That test’s design has a post of its own.
You can test the currency without a VPN. To simulate a buyer from another country in Checkout, the official doc has a testing trick. You pass a location-formatted email such as [email protected] in the Session’s customer_email field. The page presents the same currency a buyer in that country would see.
Why does “Add another price” break the mapping?
This is the gotcha that cost the house a debugging session on 2026-07-27, and it lives in a dashboard ambiguity. On a catalog product there are two similar-looking buttons:
- “+ Add another price”: creates a new Price, with a new
price_...id. - “+ Add a price by currency” (inside the existing Price): adds a currency to the same Price, same id.
The difference looks cosmetic and is structural. Every serious billing backend maps price id → plan. In Tamperlens that function even has a name, planForPriceId(), and it returns null for any id it doesn’t recognize. An unknown id must never become an upgrade.
Now follow the wrong button’s chain. You “add the BRL price” by creating a second Price, and the Brazilian buyer pays for it. The webhook arrives with a price id the app doesn’t map. The handler answers 200, because there’s nothing to retry, and applies no plan at all. The purchase completes, the money lands, and the account stays on the free plan. No log looks wrong: Stripe shows a 2xx delivery, the app recorded “unknown id, ignored”, and the paying customer opens a ticket.
The rule that got carved into the house’s ops documentation: a new currency is added to the existing Price; a new Price only when there is a new plan. And when a new Price is unavoidable (a genuine reprice), the environment variable pointing at the id has to be updated in the same act. An orphaned id on either side produces the same invisible customer.
How do you quote the right currency before checkout?
Checkout resolves the currency at payment time. But your pricing page speaks before it does. A page that says $ to someone who will be charged in R$ has broken the only promise a pricing page has. The quote and the charge have to be the same number.
Tamperlens’s answer is to quote server-side, on the server itself, from the request’s geography. Every request passing through Cloudflare’s edge reaches the origin, the server behind it, with the visitor’s country stamped in the CF-IPCountry header. Since the box has no open ports and is only reachable through a Cloudflare Tunnel, that header always comes from the edge, not from the client. The public pricing endpoint, the route the pricing page calls, reads the header and answers the whole ladder in the right currency:
const country = String(request.headers["cf-ipcountry"] ?? "").trim().toUpperCase();
const currency = country === "BR" ? "BRL" : "USD";
Three fine-grained decisions in that endpoint, all deliberate:
- A missing header falls back to USD. A request without
CF-IPCountry(local dev, a direct probe) is quoted in dollars. That’s the safe direction: USD is the Price objects’ default currency and what every non-Brazilian card pays. - The response never enters a shared cache. It’s three numbers, but they’re this visitor’s numbers. A CDN, that shared cache on the network, serving Brazil’s answer to a visitor in the US is exactly the bug the endpoint exists to prevent.
Cache-Control: no-store, private. - Country decides currency; language is a separate signal. A Brazilian in Lisbon reads the page in Portuguese and sees the price in the currency their card will pay from there. Mixing the two signals is how you produce the page that quotes in one currency and charges in another.
Why does the webhook need two idempotency mechanisms?
Stripe’s webhooks documentation, checked 2026-08-25, establishes two realities every billing handler, the code that receives these events, has to swallow. First: Stripe does not guarantee events are delivered in the order they were generated. Second: webhook endpoints may occasionally receive the same event more than once, with automatic retries for up to three days. In other words: replay and reordering, a repeated event and an out-of-order event, aren’t edge cases: they’re the contract.
What almost nobody writes down is that replay and reordering are different problems. The right protection depends on the kind of effect the event produces. In Tamperlens there are two kinds, and each got its own idempotency:
A plan change is an absolute assignment → watermark. “This account is now on plan X” is an effect that converges: applying it twice yields the same result, so replay is harmless for free. The remaining problem is ordering.
The sequence that costs money is mundane. The smaller plan’s event fails delivery. The bigger plan’s event arrives and is applied. Minutes later, the retry of the old event lands and downgrades the account that just paid for the upgrade. There is a 200 next to every delivery and nothing in the logs that reads as wrong.
The guard is a per-account watermark: the created of the last applied event is recorded, and an older event is acknowledged with a 200 and dropped. Answering an error would make Stripe retry forever an event that has already lost its turn. A fine detail: the comparison is strictly <, not <=. The created field has one-second resolution, and a real purchase emits two events within the same second; rejecting the second would be a regression, not a guard.
A credit is a delta → PRIMARY KEY. A prepaid pack is balance += N, and that converges on nothing. The watermark doesn’t help in either direction. A replay carries the same created as the original, so created < last is false and the pack would be granted again. The watermark orders events, but it does not identify them: different problems. And consulting it would drop legitimate purchases, because a credit checkout isn’t ordered against a subscription event. They’re unrelated transactions.
The right protection is one of identity: a grants table with a PRIMARY KEY on the Checkout Session id, a key that refuses two rows with the same id. A replay becomes a conflicting INSERT, and the answer is a 200 without granting again. Identity for the identity problem, ordering for the ordering problem.
Two neighboring guards that complete the handler:
- The money before the effect. For payment methods with delayed confirmation,
checkout.session.completedfires when checkout finishes, not when the money arrives. The fulfillment doc, checked 2026-08-25, says to check the Session’spayment_statusbefore delivering. It also says to listen forcheckout.session.async_payment_succeeded, which only fires once the asynchronous payment confirms. The house handler routes both events through the same fulfillment function, the delivery of what was bought, gated onpayment_status. Anunpaidsession is acknowledged and lies dormant until the async success. Or untilasync_payment_failedburies it for good, with nothing to revoke because nothing was granted. - Whose subscription is this? If more than one product bills through the same Stripe account, your endpoint receives everyone’s events. A
customer.subscription.deletedfrom the neighboring product, acting on status and customer alone, would downgrade a paying customer of yours. The downgrade path checks that the cancelled subscription is the one backing the plan. It checks by the id recorded at purchase, or, for older accounts, by its price being one you actually sell. The upgrade path was already safe by construction, because it derives the plan from the price id.
What are the three gotchas that cost real time?
They’re documented in the repository under this exact heading: “three gotchas that cost real time, recorded so they are never re-lived”.
1. The webhook endpoint URL must be exact. Not “the right domain”, but the exact URL, character by character. The reason is in the webhooks doc: Stripe counts redirect responses as failed deliveries. A registered URL that answers 301 isn’t “almost right”. It could be a www redirecting to the root domain (the apex), an old path, or a normalized trailing slash. In any of those cases, it’s an endpoint failing 100% of deliveries while the site looks perfect in a browser, which follows redirects without counting them.
2. “Add another price” mints a new price id. The entire section above. Worth repeating in one line: a currency is added to the existing Price; an id the app doesn’t map is a purchase that completes with no effect.
3. The compose environment block is a whitelist. A docker compose deployment that declares variables explicitly in the service’s environment: does not pass through what isn’t declared. It’s an allow-list: a new variable in the box’s .env does not exist for the process until it’s named there too. That’s how a new price id can be present on the server and invisible to the app. That plan answers “not configured”, everything else works, and a grep of the .env swears it’s all there. The house closed this one with a test that fails if a paid plan’s variable is missing from the compose file. It’s the same philosophy as the test that derives the published number: whatever can drift silently, a test ties down.
And a fourth, in code, that deserves the record because it was paid on the first live purchase: the webhook payload is not the SDK object. A Checkout Session retrieved through the API can carry line_items expanded. The same session arriving in a webhook does not. The handler read the plan from a hand-listed set of ids, with a line_items fallback, and left a paying customer on the free plan. The purchase fell through to a branch webhook payloads never populate. The fixes became rules. The plan travels in metadata set at checkout creation. And set membership is asked of a single predicate (isPaidPlanId()), never of a list retyped at every use site.
The summary you take home
- A Stripe Brazil account lives on two currencies: FX is restricted for the Brazil merchant, with an exception for Visa/Mastercard issued abroad. A Brazilian card pays in reais, a foreign card pays in dollars (official support, checked 2026-08-25).
- One Price, several currencies:
currency_optionson the same object, same id (doc). Each currency’s amount is a positioning decision, set by hand. And it is tied to the code by a test, because nothing in Stripe checks it for you. - “Add a price by currency”, never “Add another price”: a price id the backend doesn’t map is a purchase that completes and delivers nothing. The paying customer stays on free with a 200 in every log.
- Quote server-side, in the currency the card will pay:
CF-IPCountryat the edge, USD as the safe fallback. Keep the response out of shared caches, and let language be decided by a separate signal. - Two idempotency mechanisms, because they’re two problems: absolute assignment + a
createdwatermark for plan changes (reordering); a PRIMARY KEY on the Checkout Session id for credits (replay). The watermark doesn’t identify events and the key doesn’t order them. Don’t press one into the other’s job. - Deliver after the money: gate on
payment_status, share fulfillment betweencompletedandasync_payment_succeeded. A delayed-confirmation method earns nothing at “completed”. - The three ops gotchas: an exact webhook URL (a redirect counts as failure), currency ≠ new Price, and compose’s
environment:as a whitelist. Each one silent, each one wearing “all green”.
Need a custom technical project?
Architecture, TypeScript, APIs and automation, from prototype to production. The person answering your email is the one writing the code, and the deadline I promise is the one I can meet.
Send me a message →