Mobile integration

Learn how to the integrate the onramp for mobile use.

The onramp UI supports mobile web views and mobile browsers. We don’t support mobile SDKs.

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 when the onramp is unavailable.

Hosted 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 hosted onramp" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script type="text/javascript" src="https://crypto-js.stripe.com/stripe-crypto-js.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 via universal link
    window.location.assign('/onramp_success/' + session.id);
  }
}

You need to configure universal links to deep link /onramp_success back to your mobile app and consider providing a fallback or onramp_success page to ask users to manually switch back to your app.

Complete the purchase

Similar to a regular integration, the frontend client drives the entirety of the onramp UI. The UI is responsive to fit the screen size—as the state of the session changes and we collect more details around transaction_details, the CryptoOnrampSession object updates accordingly. Webhooks and frontend events are generated for every status transition that occurs. As shown above, by using frontend event listeners, you can redirect users back to your application user flow when the OnrampSession is complete.

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 backend to continue querying the state of CryptoOnrampSession. For example, if the user is topping up their user balance during initial setup, you could redirect users back to your application as soon as the session transitions into fulfillment_processing. You could allow users to explore the rest of your application while polling the status of the OnrampSession in the background.