Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in

Set up an Embedded onramp integrationPublic 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

  1. The embedded onramp is only available in the EU and the US (excluding Hawaii).
  2. The Onramp API is in public preview. You must submit the onramp application before you start development in a testing environment.
  3. 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
<head>
  <title>Onramp</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
  <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
</head>

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 /v1/crypto/onramp_sessions 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
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2"
  # add as many parameters as you'd like

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.

Render the Onramp UI
client-side

Import both the StripeJS and the OnrampJS bundles:

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Crypto Onramp</title>
    <meta name="description" content="A demo of the hosted onramp" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="https://js.stripe.com/clover/stripe.js"></script>
    <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
    <script src="onramp.js" defer></script>
  </head>
  <body>
    <div id="onramp-element" />
  </body>
</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 being embedded into a third-party application

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.

Was this page helpful?
YesNo