Documentation de l'API OnrampVersion bêta publique
Utilisez la documentation de l'API Onramp lors de la création de la rampe d'accès intégrable.
Référez-vous aux flux de développement suivants lors de la création de votre intégration de rampe d’accès.
Intégrer la rampe d’accès dans votre application
Avant de pouvoir utiliser le mode production, Stripe doit approuver votre demande d’inscription à la rampe d’accès.
Démarrer
Pour intégrer une application à la rampe d’accès :
Après votre inscription à Stripe, utilisez le Dashboard pour obtenir vos clés API secrètes et publiques.
Générez un objet
CryptoOnrampSessioncôté serveur.Sur le serveur, exposez un nouvel endpoint d’API (par exemple,
myserver.) qui appelle l’endpoint Stripecom/mint-onramp-session POST /v1/crypto/onramp_. Cette opération crée une session de rampe d’accès que vous pouvez utiliser avec les nouveaux utilisateurs ou les utilisateurs récurrents. Vous devez créer une session par utilisateur.sessions Exécutez la commande suivante :
Command Linecurl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u:sk_test_BQokikJOvBiI2HlWgH4olfQ2Vous recevez une réponse semblable à ce qui suit :
{ "id": "cos_0MYvmj589O8KAxCGp14dTjiw", "object": "crypto.onramp_session", "client_secret": "cos_0MYvmj589O8KAxCGp14dTjiw_secret_BsxEqQLiYKANcTAoVnJ2ikH5q002b9xzouk", "created": 1675794053, "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", "xlm" ], "destination_networks": [ "bitcoin", "ethereum", "solana", "stellar" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": null } }Cet endpoint renvoie des codes d’erreur si Stripe ne peut pas créer de sessions de rampe d’accès. Consultez la section sur la prise en charge ci-dessous pour savoir pourquoi les erreurs peuvent se produire. Nous vous recommandons de rendre le composant de la rampe d’accès conditionnel lorsqu’un utilisateur obtient un état HTTP
200lors de la création d’une session, en fournissant une interface utilisateur de secours capable de traiter les erreurs de création de session.
Utiliser le client_secret de la session sur le front-end
Pour initialiser le composant de la rampe d’accès, vous avez besoin des éléments suivants :
- Votre clé API publique.
- Le
client_de votre requête àsecret POST /v1/crypto/onramp_.sessions
Le code ci-dessous permet d’intégrer un iframe sur le nœud #onramp-element, qui héberge l’ensemble de la rampe d’accès. Vous pouvez utiliser un écouteur d’événements pour améliorer les fonctionnalités de votre application. Par exemple, vous pouvez reprendre une opération dans une application décentralisée (Dapp) après des achats de cryptomonnaies. Consultez la section sur les événements de front-end pour obtenir la liste des événements auxquels il est possible de s’abonner.
<!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 src="https://js.stripe.com/v3/"></script> <script type="text/javascript" src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script> </head> <body> <div id="onramp-element" style="max-width: 500px"> <script> const stripeOnramp = StripeOnramp(); initialize(); // initialize onramp element with client secret function initialize() { const clientSecret = "cos_1LLgeLF5fgi2FFcAWx8RlsMT_secret_WNA1VOkwZ0bHMc9MtOuyJ4vto00EMsLP7Io"; const onrampSession = stripeOnramp.createSession({clientSecret}); onrampSession .mount("#onramp-element"); } </script> </body> </html>"pk_test_TYooMQauvdEDq54NiTphI7jx"
L’élément CryptoOnramp s’affiche et prend le relais
Une fois que l’élément HTML CryptoOnramp ci-dessus s’affiche, le client front-end pilote l’interface. Comme l’état de la session change et que nous collectons davantage d’informations autour de transaction_, l’objet CryptoOnrampSession est mis à jour en conséquence. Les webhooks et les événements front-end sont générés pour chaque transition d’état qui se produit. Les écouteurs d’événement front-end vous permettent de rediriger les utilisateurs vers le flux d’utilisateurs de votre application une fois la session de rampe d’accès terminée.
(Facultatif) Modifier l’apparence de la rampe d’accès
Pour activer le mode sombre, incluez une structure d’apparence dans l’appel de création de session ci-dessus.
const onrampSession = stripeOnramp.createSession({ clientSecret: clientSecret, appearance: { theme: 'dark' }, });
Si vous ne spécifiez pas l’apparence, la rampe d’accès adopte par défaut un thème clair. Vous pouvez également modifier le thème après l’affichage de la rampe d’accès en appelant :
onrampSession.setAppearance({ theme: newTheme });
Vous pouvez utiliser vos paramètres de marque pour charger votre logo et les couleurs de votre marque, qui seront automatiquement appliqués aux sessions de rampe d’accès créées avec la clé API de votre plateforme.
Préremplir les paramètres de transaction
Pour fournir un flux utilisateur de la rampe d’accès transparent, vous pouvez préremplir certains des paramètres de la session de rampe d’accès. Par exemple, une Dapp ou un portefeuille possède déjà l’adresse wallet_ d’un utilisateur. Pour ce faire, procédez comme suit lors de la création d’une session :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \ -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \ -d "source_currency"="usd" \ -d "destination_currency"="eth" \ -d "destination_network"="ethereum" \ -d "destination_amount"="0.1234"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Vous recevez une réponse semblable à ce qui suit :
{ "id": "cos_0MYvnp589O8KAxCGwmWATYfA", "object": "crypto.onramp_session", "client_secret": "cos_0MYvnp589O8KAxCGwmWATYfA_secret_LhqXJi2lvbMCYhVHfrHGfUfX6009qtZPtV7", "created": 1675794121, "livemode": false, "status": "initialized", "transaction_details": { "destination_currency": "eth", "destination_amount": "0.123400000000000000", "destination_network": "ethereum", "fees": null, "lock_wallet_address": false, "source_currency": "usd", "source_amount": null, "destination_currencies": [ "btc", "eth", "sol", "usdc", "xlm" ], "destination_networks": [ "bitcoin", "ethereum", "solana", "stellar" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": { "bitcoin": null, "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2", "polygon": null, "solana": null, "stellar": null, "destination_tags": null } } }
Nous autorisons le préremplissage des paramètres suivants :
wallet_: adresse de portefeuille suggérée pour l’envoi de cryptomonnaie (la sélection par défaut sur l’écran du portefeuille)addresses lock_: indique si l’adresse de portefeuille suggérée doit être verrouillée ou nonwallet_ address source_: devise fiduciaire de la transaction (currency usdeteuruniquement pour le moment)source_: montant en devise fiduciaire à utiliser pour l’achat de cryptomonnaies (cet attribut et le montant de destination s’excluent mutuellement)amount destination_: réseau de cryptomonnaies par défaut pour cette rampe d’accès (par exemple,network ethereum)destination_: cryptomonnaie par défaut pour cette session de rampe d’accès (par exemple,currency eth)destination_: montant en cryptomonnaie à acheter (cet attribut et le montant source s’excluent mutuellement)amount destination_: un tableau de cryptomonnaies auxquelles vous souhaitez vous limiter (par exemple,currencies [eth, usdc])destination_: un tableau des réseaux de cryptomonnaies auxquels vous souhaitez vous limiter (par exemple,networks [ethereum, polygon]).
Veuillez vous reporter à la documentation de l’API pour en savoir plus sur les exigences spécifiques et leur impact sur les utilisateurs dans l’interface utilisateur de la rampe d’accès.
Préremplir les informations client
Afin de réduire la complexité pour l’utilisateur du flux de la rampe d’accès et d’augmenter le taux de conversion, vous pouvez préremplir certaines des informations KYC requises pour l’utilisateur si vous les avez déjà recueillies dans votre application.
Tout au long du flux, les utilisateurs doivent fournir au moins les informations suivantes :
- Adresse e-mail
- Prénom
- Nom de famille
- Date de naissance
- Numéro de sécurité sociale
- Adresse du domicile (pays, ligne 1 de l’adresse, ligne 2 de l’adresse, ville, État, code postal)
L’API Onramp permet de préremplir tous ces champs, à l’exception du numéro de sécurité sociale. Pour préremplir ces informations, vous pouvez les fournir à l’aide du paramètre customer_ dans l’API de création OnrampSession.
Exemple de requête :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \ -d "customer_information[email]"="john@doe.com" \ -d "customer_information[first_name]"="John" \ -d "customer_information[last_name]"="Doe" \ -d "customer_information[dob][year]"=1990 \ -d "customer_information[dob][month]"=7 \ -d "customer_information[dob][day]"=4 \ -d "customer_information[address][country]"="US" \ -d "customer_information[address][line1]"="354 Oyster Point Blvd" \ -d "customer_information[address][line2]"="Apt 1A" \ -d "customer_information[address][city]"="South San Francisco" \ -d "customer_information[address][state]"="CA" \ -d "customer_information[address][postal_code]"="94080"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Réponse :
{ "id": "cos_1MbuUeAEFtmWU4EVBFZS0gce", "object": "crypto.onramp_session", "client_secret": "cos_1MbuUeAEFtmWU4EVBFZS0gce_secret_zPsPPytwNU6mMKh1Bmz7ymXGi00ILwwyGeG", "created": 1676504072, "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", "xlm" ], "destination_networks": [ "bitcoin", "ethereum", "solana", "polygon", "stellar" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": null } }
Nous autorisons le préremplissage des paramètres suivants :
customer_: chaîne au format libre pour l’adresse e-mail de l’utilisateurinformation. email customer_: chaîne au format libre pour le prénom de l’utilisateurinformation. first_ name customer_: chaîne au format libre pour le nom de famille de l’utilisateurinformation. last_ name customer_: nombre entier pour l’année de naissance de l’utilisateurinformation. dob. year customer_: nombre entier pour le mois de naissance de l’utilisateurinformation. dob. month customer_: nombre entier pour le jour de naissance de l’utilisateurinformation. dob. day customer_: chaîne du code pays à deux lettres du pays de résidence de l’utilisateurinformation. address. country customer_: chaîne au format libre pour la première ligne de l’adresse de l’utilisateurinformation. address. line1 customer_: chaîne au format libre pour la deuxième ligne de l’adresse de l’utilisateurinformation. address. line2 customer_: chaîne au format libre pour la ville de l’utilisateurinformation. address. city customer_: chaîne du code d’État à deux lettres pour les États des États-Unis (le nom complet de l’État fonctionne également), par exemple « CA » ou « California »information. address. state customer_: chaîne au format libre pour le code postal de l’utilisateurinformation. address. postal_ code
Tous les champs sont facultatifs, et vous pouvez fournir n’importe quel sous-ensemble d’entre eux pour le préremplissage. Cependant, si vous indiquez la date de naissance, vous devez également fournir tous les champs year, month et day (et pas seulement un ou deux de ces champs).
Gérer la prise en charge des utilisateurs et de la fraude
Stripe impose des limitations à la rampe d’accès pour la prise en charge des utilisateurs et en cas d’attaques frauduleuses.
Vérifier la prise en charge des utilisateurs
Spécificités régionalesÉtats-UnisEU
Onramp n’est disponible qu’aux États-Unis (à l’exception d’Hawaï) et dans les pays de l’UE.
Transmettez customer_ lors de la création de la session afin que nous puissions vérifier à l’avance les limitations susmentionnées. L’endpoint renvoie HTTP 400 avec code=crypto_ si le client se trouve à un endroit que nous ne prenons pas en charge (selon sa customer_).
Dans ce cas, il se peut que vous souhaitiez masquer l’option de la rampe d’accès aux utilisateurs. Sinon, notre interface utilisateur de la rampe d’accès affiche l’état disabled.
Voici un exemple de requête et de réponse (400) illustrant ce comportement :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \ -d "customer_ip_address"="8.8.8.8" \sk_test_BQokikJOvBiI2HlWgH4olfQ2
{ "error": { "type": "invalid_request_error", "code": "crypto_onramp_unsupportable_customer", "message": "Based on the information provided about the customer, we’re currently unable to support them." } }
Gérer les attaques frauduleuses
Stripe fait office d’entité officielle et accepte la responsabilité en cas de litige et de fraude. Nous possédons une grande expertise en matière de gestion des risques, mais nous pouvons décider de restreindre temporairement la création de sessions de rampe d’accès si nous détectons une situation à haut risque (par exemple, si nous détectons des attaques et des failles actives).
Si nous devons fermer l’API en raison d’une fraude illimitée, nous renverrons le message suivant lorsqu’une personne tentera de créer une nouvelle session :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \sk_test_BQokikJOvBiI2HlWgH4olfQ2
Vous recevez une réponse semblable à ce qui suit :
{ "error": { "type": "api_error", "code": "crypto_onramp_disabled", "message": "The v1/crypto/onramp_sessions endpoint has been disabled temporarily. Stripe will get in contact with you about details of the outage.", "updated": 1652025690 } }
Documentation de l’API
Ressource CryptoOnrampSession
La ressource CryptoOnrampSession se présente comme suit :
{ "id": "cos_1Ke0052eZvKYlo2Clh7lJ50Q", "object": "crypto.onramp_session", // One of the most important parts of the resource is going to be this // client_secret. This will be passed from the server to the client to // drive a single session using our embedded widget. "client_secret": "cos_1Ke0052eZvKYlo2Clh7lJ50Q_secret_f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8", "created": 1647449225, "livemode": true, // A hash representing monetary details of the transaction this session represents "transaction_details": { // The consumer's wallet address (where crypto will be sent to) "wallet_addresses": null | { "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2", "solana": "bufoH37MTiMTNAfBS4VEZ94dCEwMsmeSijD2vZRShuV", "bitcoin": "1BuFoRu4W1usdnj1nPSfnNUgUm9BM6JtnV", "stellar": "GBUCRQX2GXV2CCPNBVB6FMXORFRNXXQMZ5RN2GMH2KZNMH7O4WON5DDN", // Mapping of assets to the destination tag where the crypto will be sent to (for supported assets) "destination_tags": null | { "xlm": "123456789" } }, // A fiat currency code "source_currency": null | "usd", "eur", // The amount of fiat we intend to onramp - excluding fees "source_amount": null | "1.01", // The selected destination_currency to convert the `source` to. // This should be a a crypto currency, currency code // If destination_currencies is set, it must be a value in that array. "destination_currency": null | "usdc", // The specific crypto network the `destination_currency` is settled on. // If destination_networks is set, it must be a value in that array. "destination_network": null | "ethereum", // If a platform wants to lock the currencies an session will support, // they can add supported currencies to this array. If left null, the experience // will allow selection of all supported destination currencies. "destination_currencies": null | ["eth", "usdc", "btc" , "xlm"], // If a platform wants to lock the supported networks, they can do so through // this array. If left null, the experience will allow selection of all // supported networks. "destination_networks": null | ["solana", "ethereum", "polygon" , "stellar"], // The amount of crypto the customer will get deposited into their wallet "destination_amount": null | "1.012345678901234567", // Details about the fees associated with this transaction // Note: The currency associated with fee is always the same as // source_currency // Note: We won't know what fees to charge until after the customer has // passed status=onboarding "fees": null | { // The cost associated with moving crypto from Stripe to the end // consumers's wallet. e.g: for ETH, this is called "gas fee", // for BTC this is a "miner's fee". "network_fee_amount": "1.23", // Stripe's cut of the transaction "transaction_fee_amount": "1.23", }, // The total amount of source currency the consumer needs to give us to // complete the transaction. Equivalent to source_amount + fees. "source_total_amount": null | "3.47", // Pointer to the on network transaction id/hash // This will only be set if the sessions hits the stauts=fulfillment_complete // and we've transferred the crypto successfully to the external wallet. // E.g: https://etherscan.io/tx/0xc2573af6b3a18e6f7c0e1cccc187a483f61d72cbb421f7166970d3ab45731a95 "transaction_id": null | "0xc2573af6b3a18e6f7c0e1cccc187a483f61d72cbb421f7166970d3ab45731a95" }, // The status of the OnrampSession. // One of = {initialized, rejected, // requires_payment, fulfillment_processing, fulfillment_complete} "status": "initialized" }
Machine à états CryptoOnrampSession
Le champ status représente une machine à états pour la session avec les états suivants :
initialized: l’application vient de créer la session de rampe d’accès côté serveur, mais le client ne l’a pas encore utilisée. Les sessions sont dans cet état jusqu’à ce que l’utilisateur s’inscrive et soit prêt à payer.rejected: nous avons rejeté le client pour une raison quelconque (échec des KYC, problèmes de contrôle des sanctions, contrôle de la fraude).requires_: l’utilisateur a terminé son inscription ou sa connexion et il accède à la page de paiement. En cas d’échec de la tentative de paiement, ils conserve cet état.payment fulfillment_: le client a finalisé son paiement. Nous n’avons pas encore envoyé la cryptomonnaie qu’il a achetée.processing fulfillment_: le client a été en mesure de finaliser le paiement de la cryptomonnaie et nous avons confirmé l’envoi.complete
Opérations CryptoOnrampSession
Tous les endpoints nécessitent une authentification avec votre clé API. L’en-tête d’authentification est omis dans les exemples de requêtes.
Les applications peuvent effectuer les opérations suivantes sur une CryptoOnrampSession :
- Créer une session
- Obtenir une session existante
Créer une session
Endpoint : POST /v1/crypto/onramp_
| Nom du paramètre | Type (facultatif ?) par défaut : ? | Détails |
|---|---|---|
| wallet_addresses | Chaîne (facultatif) par défaut : null | L’adresse du portefeuille de cryptomonnaie du client final (pour chaque réseau) à utiliser pour cette transaction.
Pour les ressources qui utilisent des balises de destination ou des mémos, vous pouvez imbriquer une carte |
| source_currency | Chaîne (facultatif) par défaut : null | La devise fiduciaire source par défaut pour la session de rampe d’accès.
|
| source_amount | Chaîne (facultatif) par défaut : null | Le montant par défaut des monnaies fiduciaires (en décimales) à échanger en cryptomonnaies.
|
| destination_networks | Tableau<String> (facultatif) par défaut : null | La liste des réseaux de cryptomonnaies de destination parmi lesquels l’utilisateur a le choix.
|
| destination_currencies | Tableau<String> (facultatif) par défaut : null | Liste des cryptomonnaies de destination parmi lesquelles l’utilisateur peut choisir.
|
| destination_network | Chaîne (facultatif) par défaut : null | Réseau de cryptomonnaies de destination par défaut.
|
| destination_currency | Chaîne (facultatif) par défaut : null | La cryptomonnaie de destination par défaut.
|
| destination_amount | Chaîne (facultatif) par défaut : null | Le montant par défaut des cryptomonnaies à échanger.
|
| customer_ip_address | Chaîne (facultatif) par défaut : null | L’adresse IP du client que la plateforme souhaite intégrer. Si l’adresse IP de l’utilisateur se trouve dans une région que nous ne prenons pas en charge, nous renvoyons un HTTP 400 avec un code d’erreur approprié. Nous prenons en charge les IPv4 et IPv6. La prise en charge géographique est à nouveau vérifiée ultérieurement au cours du flux de la rampe d’accès, ce qui permet de masquer l’option de rampe d’accès aux utilisateurs non admissibles pour une meilleure expérience utilisateur. |
Exemple de requête et de réponse :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \ -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \ -d "source_currency"="usd" \ -d "destination_currency"="eth" \ -d "destination_network"="ethereum" \ -d "destination_currencies[]"="eth" \ -d "destination_networks[]"="ethereum"sk_test_BQokikJOvBiI2HlWgH4olfQ2
{ "id": "cos_0MYvv9589O8KAxCGPm84FhVR", "object": "crypto.onramp_session", "client_secret": "cos_0MYvv9589O8KAxCGPm84FhVR_secret_IGBYKVlTlnJL8UGxji48pKxBO00deNcBuVc", "created": 1675794575, "livemode": false, "status": "initialized", "transaction_details": { "destination_currency": "eth", "destination_amount": null, "destination_network": "ethereum", "fees": null, "lock_wallet_address": false, "source_currency": "usd", "source_amount": null, "destination_currencies": [ "eth" ], "destination_networks": [ "ethereum" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": { "bitcoin": null, "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2", "polygon": null, "solana": null, "stellar": null, "destination_tags": null } } }
Obtenir une session
Endpoint : GET /v1/crypto/onramp_
| Nom du paramètre | Type (facultatif ?) par défaut : ? | Détails |
|---|---|---|
| Aucun paramètre n’est pris en charge pour cette opération ! |
Voici un exemple de requête :
curl -X GET https://api.stripe.com/v1/crypto/onramp_sessions/cos_0MYvv9589O8KAxCGPm84FhVR \ -u:sk_test_BQokikJOvBiI2HlWgH4olfQ2
Vous recevez une réponse semblable à ce qui suit :
{ "id": "cos_0MYvv9589O8KAxCGPm84FhVR", "object": "crypto.onramp_session", "client_secret": "cos_0MYvv9589O8KAxCGPm84FhVR_secret_IGBYKVlTlnJL8UGxji48pKxBO00deNcBuVc", "created": 1675794575, "livemode": false, "status": "initialized", "transaction_details": { "destination_currency": "eth", "destination_amount": null, "destination_network": "ethereum", "fees": null, "lock_wallet_address": false, "source_currency": "usd", "source_amount": null, "destination_currencies": [ "eth" ], "destination_networks": [ "ethereum" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": { "bitcoin": null, "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2", "polygon": null, "solana": null, "stellar": null, "destination_tags": null } } }
Validation et erreurs
| Condition | État HTTP | Code d’erreur |
|---|---|---|
| Nous ne sommes pas en mesure de créer de nouvelles sessions en raison d’un incident. | 400 | crypto_ |
D’après le paramètre customer_, nous ne pouvons pas prendre en charge le client indiqué. | 400 | crypto_ ou crypto_ |
Une customer_ mal formée est transmise au endpoint /v1/crypto/onramp_. | 400 | customer_ |
Les paramètres source_ et destination_ s’excluent mutuellement, mais ils sont tous les deux définis par la plateforme. | 400 | crypto_ |
L’un des paramètres destination_ et destination_ est défini, mais pas l’autre | 400 | crypto_ |
La combinaison de destination_ et destination_ n’est pas valide | 400 | crypto_ |
Le paramètre source_ est défini, mais pas source_ | 400 | crypto_ |
La valeur de source_ n’est pas un nombre positif | 400 | crypto_ |
Le paramètre destination_ est défini, mais pas destination_ | 400 | crypto_ |
La valeur de destination_ n’est pas un nombre positif | 400 | crypto_ |
La combinaison de destination_ et destination_ ne comporte aucune devise prise en charge | 400 | crypto_ |
destination_ ne figure pas dans destination_ | 400 | crypto_ |
destination_ ne figure pas destination_ | 400 | crypto_ |
Au moins une des adresses de portefeuille figurant dans wallet_ est associée à un réseau qui n’apparaît pas dans destination_ | 400 | crypto_ |
Aucune adresse de portefeuille n’a été fournie dans wallet_, alors que la valeur de lock_ est définie sur « true » | 400 | crypto_ |
L’entreprise n’a pas défini les champs business_ ou business_. Ceux-ci sont renseignés dans le Dashboard sous Public business name et Business website | 400 | crypto_ |
Récupérer plusieurs sessions
Endpoint : GET /v1/crypto/onramp_
Récupérez plusieurs sessions de rampe d’accès en même temps à l’aide de l’endpoint list.
Webhooks
Nous envoyons un webhook crypto. chaque fois que l’état d’une session de rampe d’accès change après sa création. Nous n’en envoyons pas lors de la création d’une nouvelle session. Vous pouvez configurer les webhooks dans le Dashboard.
La ressource utilisée par le webhook sera la ressource CryptoOnrampSession ci-dessus :
{ "id": "evt_123", "object": "event", "data": { "object": { "id": "cos_0MYvv9589O8KAxCGPm84FhVR", "object": "crypto.onramp_session", "client_secret": "cos_0MYvv9589O8KAxCGPm84FhVR_secret_IGBYKVlTlnJL8UGxji48pKxBO00deNcBuVc", "created": 1675794575, "livemode": false, "status": "initialized", "transaction_details": { "destination_currency": "eth", "destination_amount": null, "destination_network": "ethereum", "fees": null, "lock_wallet_address": false, "source_currency": "usd", "source_amount": null, "destination_currencies": [ "eth" ], "destination_networks": [ "ethereum" ], "transaction_id": null, "wallet_address": null, "wallet_addresses": { "bitcoin": null, "ethereum": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2", "polygon": null, "solana": null, "stellar": null, "destination_tags": null } } } } }
Événements front-end
Voici la liste des événements front-end auxquels vous pouvez vous abonner :
// when the onramp UI is rendered { type: 'onramp_ui_loaded', payload: {session: OnrampSession}, } // when the onramp session object is updated { type: 'onramp_session_updated', payload: {session: OnrampSession}, } // for modal overlay render mode only { type: 'onramp_ui_modal_opened', payload: {session: OnrampSession}, } { type: 'onramp_ui_modal_closed', payload: {session: OnrampSession}, }
Comme indiqué ci-dessus, il est possible de s’abonner à des événements et de s’en désabonner via les fonctions standard addEventListener/removeEventListener sur OnrampSession. Vous pouvez utiliser '*' pour faire correspondre tous les événements.
Persistance de session
Vous pouvez utiliser la persistance de session pour envoyer des notifications et maintenir l’intérêt des utilisateurs pour la rampe d’accès une fois leur achat effectué.
Avantages de la persistance de session
Dans certains cas, vous pouvez conserver une session de rampe d’accès pour toutes les visites des utilisateurs. Par exemple, lorsque la session de rampe d’accès d’un utilisateur est interrompue ou abandonnée, vous pouvez le lui signaler et lui proposer des moyens de reprendre la session de rampe d’accès ultérieurement. Si un utilisateur actualise la page après avoir effectué le paiement, vous pouvez conserver la possibilité de l’avertir lorsqu’un précédent achat de rampe d’accès a été traité. Pour cette raison, l’objet OnrampSession a un état et est stocké en tant que ressource côté serveur. En initialisant l’interface utilisateur de rampe d’accès à l’aide d’une clé secrète de client OnrampSession précédemment utilisée, les utilisateurs reviennent à la position où ils se sont arrêtés.
Configuration de la persistance de session
Une clé secrète du client est un identifiant unique pour la session de rampe d’accès qui stocke le cycle de vie d’une session sans divulguer d’informations de paiement sensibles. Cependant, elle expose des informations privées telles que les adresses de portefeuille. Ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne l’exposez à personne d’autre que votre client. Assurez-vous de disposer du protocole TLS sur toutes les pages qui incluent la clé secrète du client. Si vous avez une structure de compte de type Web2, vous pouvez lier la OnrampSession à votre objet utilisateur et la récupérer lors de l’authentification. Pour une application Web3 sans compte, l’utilisation de la signature de message pour l’authentification compliquerait la tâche de l’utilisateur. Le stockage local préservant la confidentialité offre une expérience utilisateur acceptable.