Stripe Embedded Onramp vs Hosted Onramp
By Shawn Michael Thomas II, Founder of Simple Easy Transactions · Published ·
Should I embed Stripe's crypto onramp in my app or send people to the Stripe-hosted onramp? If buying crypto is part of my product, like funding a new wallet, I embed Stripe's onramp so the customer never leaves. If I only need to point people somewhere safe to buy, I send them to Stripe's hosted onramp, which needs almost no code. In both, Stripe checks the buyer's identity, takes the payment and delivers the crypto to their wallet. Neither works until Stripe approves your onramp application.
AT A GLANCE
Embedded onramp vs Stripe-hosted onramp.
| Question | Embedded onramp | Stripe-hosted onramp |
|---|---|---|
| Where the customer buys | Inside your website, or your app's web view | On Stripe's own onramp page |
| What your server does | Creates an onramp session for each customer visit | Nothing for a basic link; creates a session for full branding |
| The customer's wallet address | You can fill it in and lock it | You can fill it in when your server creates the session |
| Your branding | Logo and colors from Stripe's branding settings, plus light or dark theme | Minimal for a basic link; full branding with a server-created session |
| Identity checks and fraud | Handled by Stripe | Handled by Stripe |
| Where it's available | The US (excluding Hawaii) and the EU | The US and the EU, with some coins limited by state or region |
HOW EACH ONE WORKS
How each one works.
If you're new to crypto: fiat money is ordinary currency like US dollars, a wallet is where cryptocurrency is held, and a network is the blockchain it travels on. A wallet has to support the network the coins are sent on.
Stripe's onramp lets someone buy cryptocurrency with fiat money and have it delivered to their wallet. Stripe's documentation describes Stripe as the merchant of record for those purchases: it verifies the buyer's identity, screens for sanctions and fraud, takes the payment and delivers the crypto. The business hosting the onramp never holds the money or the coins.
The hosted onramp is the lighter path. At its simplest, your page builds a link to Stripe's onramp with a suggested amount, coin and network, and sends the customer there. If you want your branding and the customer's wallet address filled in, your server creates a session first and Stripe returns a link for that session.
The embedded onramp puts the whole purchase on your page. Your server creates an onramp session for each visit, your page loads Stripe's onramp script and shows it, and the session moves through identity checks, payment and delivery. Stripe sends a webhook each time the session's status changes, and your page can listen for the same changes.
For wallet apps, embedding is usually the better fit. If your app creates a wallet for each user at sign-in, with a wallet provider such as Privy, you already know the address and network, so you can fill them in and lock them, and the customer can't send coins to the wrong place by mistake.
FIELD NOTES
What I've learned building this.
- This site has a working embedded onramp page. My server creates each session and passes along the customer's IP address, so Stripe can say straight away whether it can serve that customer, instead of showing a form that turns them away later.
- Nothing opens until the customer ticks a box agreeing to my terms, and my server checks that box before it ever asks Stripe for a session.
- Stripe's docs name the webhook crypto.onramp_session.updated, while the event your page hears is onramp_session_updated. My code accepts both spellings, so a naming slip can't silently drop an update.
HOW TO CHOOSE
How I'd choose.
- Choose the embedded onramp when buying crypto is a step inside your product, like funding a wallet right after it's created.
- Choose the hosted onramp when you just need to send people somewhere trustworthy to buy, with little or no code.
- Choose neither until Stripe has approved your onramp application. Even testing needs approval.
SOURCES
Where these facts come from.
Sources checked on . Stripe and the app stores change their products and rules, so the linked pages are the final word.