Set up an emeddable onramp integration
Build a full, working Stripe fiat-to-crypto onramp integration with your test mode API key. To customize the look and feel, go to the branding settings of the Dashboard. In the Dashboard, make sure you’ve added domains to the domain allowlist for the domains you’ll use to host the onramp page.
Install the Stripe Node library
Install the package and import it in your code. Alternatively, if you’re starting from scratch and need a package.json file, download the project files using the Download link in the code editor.
Create a OnrampSession
Add an endpoint on your server that creates an OnrampSession object. An OnrampSession
object tracks the customer’s onramp lifecycle, keeping track of order details and ensuring the customer is only charged once. Return the OnrampSession
object’s client secret in the response to finish the onramp on the client.
Note
Our official libraries don’t contain built-in support for the API endpoints because the onramp API is in limited beta. This guide includes custom extension to the official Stripe libraries for minting onramp sessions. You can find them in the downloadable sample code on the right.
Load Stripe Crypto SDK
Use Stripe.js and the Stripe crypto SDK to remain PCI compliant. These scripts must always load directly from Stripe’s domains (https://js.stripe.com and https://crypto-js.stripe.com) for compatibility. Don’t include the scripts in a bundle or host a copy yourself. If you do, your integration might break without warning.
Define the onramp container
Add one empty placeholder div
to your page to host the onramp widget. Stripe inserts an iframe to securely collect the customer’s payment and other sensitive information.
Initialize Stripe crypto SDK
Initialize Stripe crypto SDK with your publishable API keys. You’ll use it to retrieve the OnrampSession
object and complete the onramp on the client.
Fetch an OnrampSession
Immediately make a request to the endpoint on your server to create a new OnrampSession
object as soon as your page loads. The clientSecret returned by your endpoint is used to complete the onramp.
Create the OnrampElement
Create an OnrampSession
instance and mount it to the placeholder <div>
on your page. It embeds an iframe with a dynamic UI that collects necessary order, identity, and payment details to complete the purchase and delivery of crypto.
Note
Use the values provided here to complete an onramp transaction in test mode.
Enhance your integration
You’re ready to let users securely purchase cryptocurrencies directly from your platform or Dapp at checkout. Continue with the steps below to add more features.
Style the onramp widget
Customize the Onramp UI with brand settings in your dashboard. Use your company’s color scheme to make it match with the rest of your onramp page.
Apply dark mode to the onramp widget with the theme
parameter.
Set up OnrampSession state listeners
Initialize listeners to provide a responsive user interface when an onramp session completes. For example, you can direct users to resume their previous task or return to their intended destination.
Next steps
Onramp API
Customize the OnrampSession
, such as pre-populating customer information and setting default cryptocurrencies.
Onramp Quotes API
Use the Onramp Quotes API to fetch estimated quotes for onramp conversions into various cryptocurrencies on different networks.
Back-end integration best practices
Review the suggested OnrampSession
parameters to set based on your product use case.
const express = require("express");const app = express();// This is a public sample test API key.// Don’t submit any personally identifiable information in requests made with this key.// Sign in to see your own test API key embedded in code samples.const Stripe = require("stripe");const stripe = Stripe('sk_test_4eC39HqLyjWDarjtT1zdp7dc');const OnrampSessionResource = Stripe.StripeResource.extend({create: Stripe.StripeResource.method({method: 'POST',path: 'crypto/onramp_sessions',}),});app.use(express.static("public"));app.use(express.json());app.post("/create-onramp-session", async (req, res) => {const { transaction_details } = req.body;// Create an OnrampSession with the order amount and currencyconst onrampSession = await new OnrampSessionResource(stripe).create({transaction_details: {destination_currency: transaction_details["destination_currency"],destination_exchange_amount: transaction_details["destination_exchange_amount"],destination_network: transaction_details["destination_network"],},customer_ip_address: req.socket.remoteAddress,});res.send({clientSecret: onrampSession.client_secret,});});app.listen(4242, () => console.log("Node server listening on port 4242!"));
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8" /><title>Crypto Onramp</title><meta name="description" content="A demo of Stripe onramp" /><meta name="viewport" content="width=device-width, initial-scale=1" /><link rel="stylesheet" href="onramp.css" /><script src="https://js.stripe.com/v3/"></script><script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script><script src="onramp.js" defer></script></head><body><div id="root"><div id="onramp-message"></div><div id="onramp-element"><!--Stripe injects the Onramp widget--></div></div></body></html>
// This is a public sample test API key.// Don’t submit any personally identifiable information in requests made with this key.// Sign in to see your own test API key embedded in code samples.const stripeOnramp = StripeOnramp("pk_test_TYooMQauvdEDq54NiTphI7jx");let session;initialize();async function initialize() {// Fetches an onramp session and captures the client secretconst response = await fetch("/create-onramp-session",{method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({transaction_details: {destination_currency: "usdc",destination_exchange_amount: "13.37",destination_network: "ethereum",}}),});const { clientSecret } = await response.json();session = stripeOnramp.createSession({clientSecret,appearance: {theme: "dark",}}).addEventListener('onramp_session_updated', (e) => {showMessage(`OnrampSession is now in ${e.payload.session.status} state.`)}).mount("#onramp-element");}// ------- UI helpers -------function showMessage(messageText) {const messageContainer = document.querySelector("#onramp-message");messageContainer.textContent = messageText;}
* {box-sizing: border-box;}body {font-family: -apple-system, BlinkMacSystemFont, sans-serif;font-size: 16px;-webkit-font-smoothing: antialiased;display: flex;justify-content: center;align-content: center;height: 100vh;width: 100vw;}#root {display: flex;flex-direction: column;}#onramp-message {color: rgb(105, 115, 134);font-size: 16px;line-height: 20px;padding-top: 12px;text-align: center;}#onramp-element {min-width: min(450px, 60vw);margin-top: 24px;}
{"name": "stripe-sample","version": "1.0.0","description": "A sample Stripe implementation","main": "server.js","scripts": {"start": "node server.js"},"author": "stripe-samples","license": "ISC","dependencies": {"express": "^4.17.1","stripe": "^13.0.0"}}
# Integrate with Stripe onrampBuild a simple page to use Stripe onramp. Included are some basicbuild and run scripts you can use to start up the application.## Running the sample1. Build the server~~~npm install~~~2. Run the server~~~npm start~~~3. Go to [http://localhost:4242/onramp.html](http://localhost:4242/onramp.html)