Public preview

Set up an Embedded onramp integration Public preview

Use this guide to fully customize the embeddable onramp.

This guide is an extended version of the Embedded onramp quickstart. Learn to add more functionality such as how to:

Install the SDK using a script tag or package manager
Customize the onramp appearance
Configure the onramp UI into mobile web views
Handle customer supportability and fraud
Fetch estimated cryptocurrency conversion quotes

Before you begin

The embedded onramp is only available in the EU and the US (excluding Hawaii).
The Onramp API is in public preview. You must submit the onramp application before you start development in a testing environment.
After you get access to the Onramp API , use the Dashboard to grab your secret and publishable API keys .

Install the SDK and client library client-side server-side

Client-side

Include the following scripts using script tags within the <head> element of your HTML. These scripts must always load directly from Stripe’s domains (https://js.stripe.com and https://crypto-js.stripe.com) for compatibility and PCI compliance.

Don’t include the scripts in a bundle or host a copy yourself because your integration might break without warning.

onramp.html

JS SDK

Use the npm package to load the onramp JS SDK as an ES module. The package includes Typescript type definitions.

npm install --save @stripe/stripe-js @stripe/crypto

Alternative SDK installation

Server-side

Our official libraries don’t contain built-in support for the API endpoints because the Onramp API is in public preview. As a result, our examples use curl for backend interactions.

Create a crypto onramp session server-side

On the server, expose a new API endpoint (for example, myserver.com/mint-onramp-session) that makes a call to the Stripe POST /the relevant part of the product endpoint. This mints an onramp session with Stripe you can use with new or returning customers. You must mint one session per customer.

Create a crypto onramp session by running the following curl command in your terminal:

Command Line

You receive a response similar to the following:

{
 "id": "cos_0MYfrA589O8KAxCGEDdIVYy3",
 "object": "crypto.onramp_session",
 "client_secret": "cos_0MYfrA589O8KAxCGEDdIVYy3_secret_rnpnWaxQbYQOvp6nVMvEeczx300NRU4hErZ",
 "created": 1675732824,
 "livemode": false,
 "status": "initialized",
 "transaction_details": {
 "destination_currency": null,
 "destination_amount": null,
 "destination_network": null,
 "fees": null,
 "lock_wallet_address": false,
 "source_currency": null,
 "source_amount": null,
 "destination_currencies": [
 "btc",
 "eth",
 "sol",
 "usdc"
 ],
 "destination_networks": [
 "bitcoin",
 "ethereum",
 "solana"
 ],
 "transaction_id": null,
 "wallet_address": null,
 "wallet_addresses": {
 "bitcoin": null,
 "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2",
 "polygon": null,
 "solana": null
 }
 }
}

Errors

This endpoint returns error codes if Stripe can’t create onramp sessions. To learn why this might happen, see Handle customer supportability and fraud. We recommend that you render the onramp component conditional when a customer gets an HTTP status 200 during session creation, providing a fallback UI that can deal with session creation errors.

For the full parameter list you can pass when creating a session, see the Onramp API.

States

Each onramp session progresses through the following states:

initialized : The app has newly minted the onramp session on the server-side, but the customer hasn’t used it yet. Sessions are in this state until the customer onboards and is ready to pay.
rejected : Stripe rejected the customer for some reason (KYC failure, sanctions screening issues, fraud checks).
requires _ payment : The customer has completed onboarding or sign-in and gets to the payment page. If they attempt payment and fail, they stay in this state.
fulfillment _ processing : The customer successfully completed payment. We haven’t delivered the crypto they purchased yet.
fulfillment _ complete : The customer was successfully able to pay for crypto and we have confirmed delivery.

Optional Customize the appearance of the onramp

Optional Pre-populate parameters

Render the Onramp UI client-side

Import both the StripeJS and the OnrampJS bundles:

index.html

Use the client_secret from your server-side call in the previous step to initiate and mount the onramp session:

onramp.js

const stripeOnramp = StripeOnramp("pk_test_TYooMQauvdEDq54NiTphI7jx");
initialize();
// Initialize the onramp element with a client secret
function initialize() {
 // IMPORTANT: replace the following with your logic of how to mint/retrieve the client secret
 const clientSecret = "cos_1Lb6vsAY1pjOSNXVWF3nUtkV_secret_8fuPvTzBaxj3XRh14C6tqvdl600rpW7hG4G";
 const onrampSession = stripeOnramp.createSession({clientSecret});
 onrampSession
 .mount("#onramp-element");
}

After running the script, the onramp renders the following dialog:

Stripe’s fiat-to-crypto onramp embedded within a third-party application

Sandbox values

Warning

Sandbox transaction amounts are overridden by our pre-decided limits.

Use the following values to complete an onramp transaction in sandbox:

On the OTP screen, use 000000 for the verification code.
On the personal information screen, use 000000000 for the SSN and address _ full _ match for address line 1.
On the payment details screen, use the test credit card number 4242424242424242 .

View integration usage

After you’ve launched the onramp, you can view customized usage reports in the Stripe Dashboard. You can also return to the onboarding page to update the domains where you plan to host the onramp, and check the status of any onboarding tasks.

Set up an Embedded onramp integration