Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

Set up an embeddable onramp integrationPublic preview

Use this guide to fully customize the embeddable onramp.

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

  • Installing the SDK using a script tag or package manager
  • Fetching estimated quotes for onramp conversions into cryptocurrencies
  • Configuring the onramp UI into mobile web views

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. If you do, your integration might break without warning.

onramp.html
<head>
  <title>Onramp</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
</head>

Use the Onramp JS SDK as a module

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

Alternate SDK installation

Alternatively, you can install the Stripe Crypto ES module client-side SDK using a script tag or package manager. The SDK wraps the global StripeOnramp function provided by the Stripe crypto script as an ES module.

  1. Manually load the script. 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. If you do, your integration might break without warning.

    <head>
  <title>Onramp</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
</head>

  2. Set the API publishable key to allow Stripe to retrieve the OnrampSession object created by your back end. For example:

    const stripeOnramp = StripeOnramp(
    'pk_test_TYooMQauvdEDq54NiTphI7jx'
    );

  3. To install the module through the package manager, first install the Stripe.js ES module and Stripe crypto ES module from the npm public registry. The package includes Typescript type definitions.

    Command Line
    npm install @stripe/stripe-js @stripe/crypto

  4. Import the module and set the API publishable key to allow Stripe to retrieve the OnrampSession object created by your back end. The function returns a Promise object that resolves with a newly created StripeOnramp object after the scripts load.

    import {loadStripeOnramp} from '@stripe/crypto';

const stripeOnramp = await loadStripeOnramp(
    'pk_test_TYooMQauvdEDq54NiTphI7jx'
    );

Server-side

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

Generate a crypto onramp session
server-side

Generate 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
    }
  }
}

See the Onramp API reference for the full parameter list you can pass in when creating a session.

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/basil/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.

OptionalConfigure the onramp for mobile use

Integrate Stripe’s crypto onramp UI into mobile web views and browsers by minting a session, hosting the onramp UI, completing the purchase, and redirecting users back to the mobile app.

Mint a session

Similar to other integrations, you need to implement a server endpoint to create a new onramp session for every user visit. The endpoint returns a client_secret that can load the onramp UI or display an error if the onramp is unavailable.

Host the onramp UI

Create a frontend route (for example, www.my-web3-wallet.com/onramp/<client_secret>) to host the onramp UI. Your /onramp/<client_secret> points to an onramp.html.

onramp.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 type="text/javascript" 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>

Where onramp.js consumes the client_secret from the URL and mounts the onramp UI:

onramp.js
const stripeOnramp = StripeOnramp(
pk_test_TYooMQauvdEDq54NiTphI7jx
);
initialize();
// initialize onramp element with client secret
function initialize() {
  const url = window.location.href.replace(/\/$/, '');
  const clientSecret = url.substring(url.lastIndexOf('/') + 1);
  const onrampSession = stripeOnramp.createSession({
    clientSecret,
    // other client side options that customize the look and feel
  });
  onrampSession
    .addEventListener('onramp_session_updated', handleSessionUpdate)
    .mount("#onramp-element");
}
function handleSessionUpdate(event) {
  const session = event.payload.session;
  if (session.status === 'fulfillment_complete' || session.status === 'rejected') {
    // redirect back to mobile app through universal link
    window.location.assign('/onramp_success/' + session.id);
  }
}

Configure universal links to deep link /onramp_success back to your mobile app. Consider providing a fallback or onramp_success page to prompt users to manually switch back to your app.

Complete the purchase

As with a standard integration, the front-end client controls the entire onramp UI. The UI adapts to fit the screen size. As the session state changes and we gather more transaction_details, the CryptoOnrampSession object updates accordingly. We generate webhooks and front-end events for every status transition. By using front-end event listeners, you can redirect users back to your application flow when the OnrampSession completes.

Redirect to the mobile app

Using a deep link or manual switch, users can resume their flow in your mobile application. Your mobile application can use your back end to continue querying the CryptoOnrampSession state.

For example, if a user is topping up their balance during initial setup, you can redirect them back to your application as soon as the session transitions to fulfillment_processing. You can allow users to explore the rest of your application while polling the OnrampSession status in the background.

OptionalConfigure conversion quotes

The Onramp Quotes API lets you fetch estimated quotes for onramp conversions into various cryptocurrencies on different networks. You can specify a fixed source or destination amount and limit the quotes to a subset of destination currencies or networks. This API allows you to display quotes in your product UI before directing the user to the onramp widget. If the quote expires before the user visits the onramp widget, the user might see a slightly different quote in the onramp widget.

Get a conversion quote

Use the GET /v1/crypto/onramp/quotes endpoint to get a conversion quote. The following table captures all of the available parameters for this endpoint:

ParameterTypeDefaultDetails
source_currencyString (optional)usdThe ISO-4217 currency code. We currently only support usd and eur.
source_amountString (optional)100.00A string representation of the fiat amount that you need to onramp. If source_amount is set, destination_amount must be null (they’re mutually exclusive, because you can only set a fixed amount for one end of the trade).
destination_amountString (optional)nullA string representation of the amount of destination_currency to be purchased. If destination_amount is set, source_amount must be null. When specifying this field, you must also set a single value for destination_currencies and a single value for destination_networks (so we know what cryptocurrency to quote).
destination_currenciesArray<String> (optional)null
  • ['usdc', 'ethereum']
The list of cryptocurrencies you want to generate quotes for. If left null, we retrieve quotes for all destination_currencies that destination_networks supports.
  • Currencies: btc, eth, sol, matic, usdc, xlm
destination_networksArray<String> (optional)null
  • ['polygon', 'bitcoin', 'solana', 'ethereum']
The list of cryptocurrency networks you want to generate quotes for. If left null, we retrieve quotes for destination_currencies in all networks.
  • Networks: bitcoin, ethereum, solana, polygon , stellar

Example quote requests

To fetch all destination currency-network pairs with a default source amount of 100 USD, run the following command:

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

You receive a response similar to the following:

{
  "id": "cd35838481497f403988360cc0ff5ce5c5ce7451ce8938f86d379dff7157d33d",
  "rate_fetched_at": 1674265380.6883376,
  "destination_network_quotes": {
    "ethereum": [
      {
        "id": "7eb9ccb7c1bffadf3773ca1f56ba3a352fe4a226328e72142925a80e7242b70c",
        "destination_currency": "eth",
        "destination_amount": "0.060232255577506866",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "1.41",
          "transaction_fee_monetary": "3.03"
        },
        "source_total_amount": "104.44"
      },
      {
        "id": "398de047128b6dff1abbc41519811db68dd8bcb69939b87c4a4621b1740a1c5b",
        "destination_currency": "usdc",
        "destination_amount": "100.00",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "5.63",
          "transaction_fee_monetary": "3.07"
        },
        "source_total_amount": "108.70"
      }
    ],
    ...
  },
  "livemode": true,
  "source_currency": "usd",
  "source_amount": "100.00"
}

To fetch all destination currency-network pairs with a source amount of 200 USD, run the following command:

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
    -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
    -d "source_amount"="200"

You receive a response similar to the following:

{
  "id": "2e5818944df6a2325c7e9c1e72d27174b9bedfc8e64ace47c081370a5b982a7b",
  "rate_fetched_at": 1674265506.3408287,
  "destination_network_quotes": {
    "ethereum": [
      {
        "id": "d160a80828eabb6b6d4aeafac585eee62d95425c7fb7577866ab04b9a786df00",
        "destination_currency": "eth",
        "destination_amount": "0.253568242640499553",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "1.45",
          "transaction_fee_monetary": "12.71"
        },
        "source_total_amount": "214.20"
      },
      {
        "id": "53f864cb28a42f11e1d9d5aff7e43ac96b056406f74cbf618399c6fa40f3d275",
        "destination_currency": "usdc",
        "destination_amount": "200.00",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "5.80",
          "transaction_fee_monetary": "12.76"
        },
        "source_total_amount": "218.56"
      }
    ],
    ...
  },
  "livemode": true,
  "source_currency": "usd",
  "source_amount": "200.00"
}

To fetch quotes for ETH and SOL on the Ethereum and Solana networks, run the following command (which results in ETH on Ethereum and SOL on Solana). When you specify destination_currencies and destination_networks, each valid currency-network pair in their cross-product returns a quote. The default value for destination_currencies is all currencies, and the default value for destination_networks is all networks.

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
      -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
      -d "source_amount"="200" \
      -d "destination_currencies[]"="eth" \
      -d "destination_currencies[]"="sol" \
      -d "destination_networks[]"="ethereum" \
      -d "destination_networks[]"="solana"

You receive a response similar to the following:

{
  "id": "c9ab6fd14f87290ef94b583f0dd346de8e197321e029776c12b7790cd83fb78c",
  "rate_fetched_at": 1674265576.8238478,
  "destination_network_quotes": {
    "bitcoin": [],
    "ethereum": [
      {
        "id": "97bbd7b9f8bc1a029264cdc28b47b636e989f8bcab96a80a3bded2094131e311",
        "destination_currency": "eth",
        "destination_amount": "0.253433817682353791",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "1.46",
          "transaction_fee_monetary": "12.71"
        },
        "source_total_amount": "214.17"
      }
    ],
    "polygon": [],
    "solana": [
      {
        "id": "79f00923b96543aa69d140172c7cefd0e73a2ed089d8935e63dcf21028698e23",
        "destination_currency": "sol",
        "destination_amount": "16.767237943",
        "destination_network": "solana",
        "fees": {
          "network_fee_monetary": "0.01",
          "transaction_fee_monetary": "12.70"
        },
        "source_total_amount": "212.71"
      }
    ]
  },
  "livemode": true,
  "source_currency": "usd",
  "source_amount": "200.00"
}

To fetch quotes for USDC on Ethereum and Solana, run the following command:

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "source_amount"="200" \
  -d "destination_currencies[]"="usdc" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_networks[]"="solana"

You receive a response similar to the following:

{
  "id": "8727e8de9a22915aea079973028054e31d362a328758a5953cee6ba1b6f22569",
  "rate_fetched_at": 1674268717.432479,
  "destination_network_quotes": {
    "bitcoin": [],
    "ethereum": [
      {
        "id": "603f29933c921d59b169572cf2d61da7d88f2a6973da0d6fcb686b3dec3de223",
        "destination_currency": "usdc",
        "destination_amount": "200.00",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "5.88",
          "transaction_fee_monetary": "12.76"
        },
        "source_total_amount": "218.64"
      }
    ],
    "polygon": [],
    "solana": [
      {
        "id": "38b8388072e6272e7a0c0d5ee1161d3d747362a574f54fe76f1554ff60e3a007",
        "destination_currency": "usdc",
        "destination_amount": "200.00",
        "destination_network": "solana",
        "fees": {
          "network_fee_monetary": "0.01",
          "transaction_fee_monetary": "12.70"
        },
        "source_total_amount": "212.71"
      }
    ]
  },
  "livemode": true,
  "source_currency": "usd",
  "source_amount": "200.00"
}

To fetch a quote for a single destination currency-network pair (ETH on Ethereum) with destination_amount specified, run the following command:

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "destination_amount"="0.42" \
  -d "destination_currencies[]"="eth" \
  -d "destination_networks[]"="ethereum"

You receive a response similar to the following:

{
  "id": "74f73859a8836293ce4f1e6757dc258c9f1016deea7b075faba8b5755d163168",
  "rate_fetched_at": 1674268804.6989243,
  "destination_network_quotes": {
    "bitcoin": null,
    "ethereum": [
      {
        "id": "f1adad5680b081031b03b89c174d25ce6b609416fc82f976423e95a089a10334",
        "destination_currency": "eth",
        "destination_amount": "0.420000000000000000",
        "destination_network": "ethereum",
        "fees": {
          "network_fee_monetary": "1.45",
          "transaction_fee_monetary": "21.06"
        },
        "source_total_amount": "719.53"
      }
    ],
    "polygon": null,
    "solana": null
  },
  "livemode": true,
  "source_currency": "usd",
  "source_amount": "697.02"
}
Was this page helpful?
YesNo