Configurer une intégration de rampe d'accès intégrableVersion bêta publique

Comment personnaliser entièrement la rampe d'accès intégrable.

Ce guide est une version étendue du démarrage rapide de la rampe d’accès intégrable. Découvrez comment ajouter d’autres fonctionnalités telles que :

Installation du SDK à l’aide d’une balise de script ou d’un gestionnaire de paquets
Récupération de devis estimés pour les conversions de rampe d’accès en cryptomonnaies
Configuration de l’interface utilisateur de la rampe d’accès dans les vues web mobiles

Installez le SDK et la bibliothèque client
côté client
côté serveur

Côté client

Incluez les scripts suivants à l’aide de balises de script dans l’élément <head> de votre HTML. Ces scripts doivent toujours se charger directement depuis les domaines de Stripe (https://js.stripe.com and https://crypto-js.stripe.com) à des fins de compatibilité et de conformité PCI. Vous ne devez pas inclure le script dans un bundle ni en héberger de copie. Dans le cas contraire, votre intégration pourrait s’interrompre sans avertissement préalable.

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>

Utiliser le SDK Onramp JS en tant que module

Utilisez le paquet npm pour charger le SDK JS de la rampe d’accès en tant que module ES. Le paquet inclut les définitions de type TypeScript.

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

Autre méthode d’installation du SDK

Alternativement, vous pouvez installer le SDK client module ES crypto de Stripe à l’aide d’une balise de script ou d’un gestionnaire de paquets. Le SDK encapsule la fonction globale StripeOnramp fournie par le script crypto de Stripe en tant que module ES.

Chargez manuellement le script. Incluez les scripts suivants à l’aide de balises de script dans l’<head>élément de votre HTML. Ces scripts doivent toujours être chargés directement depuis les domaines de Stripe, https://js.stripe.com et https://crypto-js.stripe.com, pour des raisons de compatibilité et de conformité PCI. N’incluez pas les scripts dans un paquet et n’en hébergez pas de copie vous-même. Dans le cas contraire, votre intégration pourrait cesser de fonctionner sans avertissement.
```
<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>
```
Définissez la clé API publiable pour permettre à Stripe de récupérer l’objet OnrampSession créé par votre back-end. Par exemple :
```
const stripeOnramp = StripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');
```
Pour installer le module via le gestionnaire de paquets, installez d’abord le module ES Stripe.js et le module ES crypto de Stripe depuis le registre public npm. Le paquet inclut les définitions de type TypeScript.
Command Line
```
npm install @stripe/stripe-js @stripe/crypto
```
Importez le module et définissez la clé API publiable pour permettre à Stripe de récupérer l’objet OnrampSession créé par votre back-end. La fonction renvoie un objet Promise qui se résout avec un nouvel objet StripeOnramp une fois les scripts chargés.
```
import {loadStripeOnramp} from '@stripe/crypto';

const stripeOnramp = await loadStripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');
```

Côté serveur

Nos bibliothèques officielles ne prennent pas en charge les endpoints de l’API de manière intégrée, car l’API Onramp est actuellement en version bêta limitée. Par conséquent, nos exemples utilisent curl pour les interactions avec le back-end.

Générer une session de rampe d'accès à la cryptomonnaie
côté serveur

Générez une session de rampe d’accès à la cryptomonnaie en exécutant la commande curl suivante sur votre terminal :

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2"
  # add as many parameters as you'd like

Vous recevez une réponse semblable à ce qui suit :

{
  "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
    }
  }
}

Consultez la documentation de l’API Onramp pour obtenir la liste complète des paramètres que vous pouvez transmettre lors de la création d’une session.

Afficher l'interface utilisateur de la rampe d'accès
côté client

Importez les bundles StripeJS et OnrampJS :

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>

Utilisez le client_secret issu de votre appel côté serveur de l’étape précédente pour initier et monter la session de rampe d’accès :

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");
}

Après l’exécution du script, la rampe d’accès restitue le dialogue qui suit :

Intégration de la rampe d’accès à la cryptomonnaie de Stripe dans une application tierce

Valeurs d’environnement de test

Avertissement

Les montants des transactions des environnements de test sont remplacés par nos limites prédéterminées.

Utilisez les valeurs suivantes pour effectuer une transaction de rampe d’accès dans un environnement de test :

Sur l’écran OTP, utilisez 000000 comme code de vérification.
Sur l’écran des informations personnelles, utilisez 000000000 pour le numéro de sécurité sociale et address_full_match pour la ligne d’adresse 1.
Sur l’écran des données de paiement, utilisez le numéro de carte de test 4242424242424242.

Consulter l'utilisation de l'intégration

Après avoir lancé la rampe d’accès, vous pouvez consulter des rapports sur l’utilisation personnalisés dans le Dashboard Stripe. Vous pouvez également revenir à la page d’inscription pour mettre à jour les domaines dans lesquels vous prévoyez d’héberger la rampe d’accès et consulter l’état des tâches d’inscription.

FacultatifConfigurer la rampe d’accès pour une utilisation mobile

Intégrez l’interface utilisateur de la rampe d’accès crypto de Stripe dans les vues web et les navigateurs mobiles en créant une session, en hébergeant l’interface utilisateur de la rampe d’accès, en finalisant l’achat et en redirigeant les utilisateurs vers l’application mobile.

Créer une session

Comme pour les autres intégrations, vous devez implémenter un endpoint de serveur pour créer une nouvelle session de rampe d’accès à chaque visite d’utilisateur. L’endpoint renvoie une client_secret qui peut charger l’interface utilisateur de la rampe d’accès ou afficher une erreur si la rampe d’accès n’est pas disponible.

Héberger l’interface utilisateur de la rampe d’accès

Créez une route front-end (par exemple, www.my-web3-wallet.com/onramp/<client_secret>) pour héberger l’interface utilisateur de la rampe d’accès. Votre /onramp/<client_secret> pointe vers un fichier 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>

Où onramp.js consomme la client_secret depuis l’URL et monte l’interface utilisateur de la rampe d’accès :

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);
  }
}

Configurez des liens universels pour créer un lien profond de /onramp_success vers votre application mobile. Pensez à fournir une solution de repli ou une page onramp_success pour inviter les utilisateurs à revenir manuellement à votre application.

Finaliser l’achat

Comme pour une intégration standard, le client front-end contrôle toute l’interface utilisateur de la rampe d’accès. L’interface utilisateur s’adapte à la taille de l’écran. À mesure que l’état de la session change et que nous recueillons plus de transaction_details, l’objet CryptoOnrampSession se met à jour en conséquence. Nous générons des webhooks et des événements front-end pour chaque transition d’état. En utilisant des écouteurs d’événements front-end, vous pouvez rediriger les utilisateurs vers le flux de votre application lorsque la OnrampSession est terminée.

Rediriger vers l’application mobile

À l’aide d’un lien profond ou d’un basculement manuel, les utilisateurs peuvent reprendre leur parcours dans votre application mobile. Votre application mobile peut utiliser votre back-end pour continuer à interroger l’état de la CryptoOnrampSession.

Par exemple, si un utilisateur recharge son solde lors de la configuration initiale, vous pouvez le rediriger vers votre application dès que la session passe à l’état fulfillment_processing. Vous pouvez autoriser les utilisateurs à explorer le reste de votre application tout en interrogeant l’état de la OnrampSession en arrière-plan.

FacultatifConfigurer les devis de conversion

L’API Onramp Quotes vous permet de récupérer des devis estimés pour les conversions de rampe d’accès en diverses cryptomonnaies sur différents réseaux. Vous pouvez spécifier un montant source ou de destination fixe et limiter les devis à un sous-ensemble de devises ou de réseaux de destination. Cette API vous permet d’afficher les devis dans l’interface utilisateur de votre produit avant de diriger l’utilisateur vers le widget de la rampe d’accès. Si le devis expire avant que l’utilisateur ne consulte le widget de la rampe d’accès, l’utilisateur pourrait voir un devis légèrement différent dans le widget.

Obtenir un devis de conversion

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:

Paramètre	Type	Par défaut	Détails
`source_currency`	String (facultatif)	`usd`	Le code de devise ISO-4217. Nous ne prenons actuellement en charge que `usd` et `eur`.
`source_amount`	String (facultatif)	`100,00`	Une représentation textuelle du montant en monnaie fiduciaire que vous devez convertir. Si `source_amount` est défini, `destination_amount` doit être null (ils sont mutuellement exclusifs, car vous ne pouvez définir un montant fixe que pour une seule des deux extrémités de la transaction).
`destination_amount`	String (facultatif)	`null`	Une représentation textuelle du montant de `destination_currency` à acheter. Si `destination_amount` est défini, `source_amount` doit être null. Lorsque vous spécifiez ce champ, vous devez également définir une seule valeur pour `destination_currencies` et une seule valeur pour `destination_networks` (afin que nous sachions pour quelle cryptomonnaie établir le devis).
`destination_currencies`	Array<String> (facultatif)	`null` `[\'usdc\', \'ethereum\']`	La liste des cryptomonnaies pour lesquelles vous souhaitez générer des devis. Si ce champ est laissé `null`, nous récupérons les devis pour toutes les `destination_currencies` prises en charge par les `destination_networks`. Devises : `btc`, `eth`, `sol`, `matic`, `usdc`, `xlm`
`destination_networks`	Array<String> (facultatif)	`null` `[\'polygon\', \'bitcoin\', \'solana\', \'ethereum\']`	La liste des réseaux de cryptomonnaies pour lesquels vous souhaitez générer des devis. Si ce champ est laissé `null`, nous récupérons les devis pour les `destination_currencies` sur tous les réseaux. Réseaux : `bitcoin`, `ethereum`, `solana`, `polygon` , `stellar`

Exemples de requêtes de devis

Pour récupérer toutes les paires devise-réseau de destination avec un montant source par défaut de 100 USD, exécutez la commande suivante :

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

Vous recevez une réponse semblable à ce qui suit :

{
  "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"
}

Pour récupérer toutes les paires devise-réseau de destination avec un montant source de 200 USD, exécutez la commande suivante :

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

Vous recevez une réponse semblable à ce qui suit :

{
  "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"
}

Pour récupérer des devis pour ETH et SOL sur les réseaux Ethereum et Solana, exécutez la commande suivante (ce qui donnera ETH sur Ethereum et SOL sur Solana). Lorsque vous spécifiez destination_currencies et destination_networks, chaque paire devise-réseau valide dans leur produit croisé renvoie un devis. La valeur par défaut pour destination_currencies est toutes les devises, et la valeur par défaut pour destination_networks est tous les réseaux.

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

Vous recevez une réponse semblable à ce qui suit :

{
  "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"
}

Pour récupérer des devis pour l’USDC sur Ethereum et Solana, exécutez la commande suivante :

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

Vous recevez une réponse semblable à ce qui suit :

{
  "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"
}

Pour récupérer un devis pour une seule paire devise-réseau de destination (ETH sur Ethereum) avec destination_amount spécifié, exécutez la commande suivante :

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

Vous recevez une réponse semblable à ce qui suit :

{
  "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"
}

Configurer une intégration de rampe d'accès intégrableVersion bêta publique

Comment personnaliser entièrement la rampe d'accès intégrable.

Installez le SDK et la bibliothèque clientcôté clientcôté serveur

Côté client

Utiliser le SDK Onramp JS en tant que module

Autre méthode d’installation du SDK

Côté serveur

Générer une session de rampe d'accès à la cryptomonnaiecôté serveur

Afficher l'interface utilisateur de la rampe d'accèscôté client

Valeurs d’environnement de test

Avertissement

Consulter l'utilisation de l'intégration

FacultatifConfigurer la rampe d’accès pour une utilisation mobile

Créer une session

Héberger l’interface utilisateur de la rampe d’accès

Finaliser l’achat

Rediriger vers l’application mobile

FacultatifConfigurer les devis de conversion

Obtenir un devis de conversion

Exemples de requêtes de devis

Installez le SDK et la bibliothèque client
côté client
côté serveur

Générer une session de rampe d'accès à la cryptomonnaie
côté serveur

Afficher l'interface utilisateur de la rampe d'accès
côté client