Utilisation de l'APIBêta
Référez-vous aux flux de développement suivants lors de la création de votre intégration de rampe d’accès.
Comment intégrer la rampe d’accès dans votre application
L’intégration d’une application pour utiliser la rampe d’accès nécessite les éléments suivants :
- Inscrivez-vous sur Stripe et obtenez vos clés API
Accédez au Dashboard et obtenez :
- Clé secrète dont vous avez besoin pour effectuer des appels d’API vers Stripe depuis un serveur que vous contrôlez
- Clé publiable que vous utilisez pour effectuer des requêtes depuis votre client front-end
- Générer un objet CryptoOnrampSession côté serveur
Note
Votre inscription à la rampe d’accès doit d’abord être approuvée avant que vous puissiez accéder au mode production. Apprenez-en davantage sur l’envoi d’une demande ou vérifiez l’état de votre demande en consultant la page d’inscription.
Sur un serveur que vous contrôlez, exposez un nouveau endpoint d’API (par exemple, myserver.com/mint-onramp-session
) qui appelle l’endpoint Stripe POST /v1/crypto/onramp_sessions
. Cette opération ouvre une session de rampe d’accès que vous pouvez utiliser avec les nouveaux utilisateurs ou les utilisateurs récurrents. Vous devez ouvrir une session par utilisateur.
La requête :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u
:sk_test_4eC39HqLyjWDarjtT1zdp7dc
La réponse :
{ "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 parvient pas à créer des sessions de rampe d’accès. Consultez la section relative à la prise en charge ci-dessous pour savoir pourquoi cela peut se produire.
Note
Pour une expérience utilisateur optimale, rendez le composant de la rampe d’accès conditionnel lorsqu’un utilisateur obtient un état HTTP 200
lors de la création d’une session et fournissez 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 aurez besoin des éléments suivants :
- Votre clé API publiable de l’étape 1
- Le client_secret de votre requête à
POST /v1/crypto/onramp_sessions
à l’étape 2 ci-dessus
<!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"
Le code ci-dessus 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 l’expérience utilisateur, par exemple en reprenant une opération dans une Dapp après des achats de cryptomonnaies (voir la section sur les événements de front-end pour tous les événements auquel il est possible de s’abonner).
- 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_details
, 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.
Comment préremplir les paramètres de transaction
Pour fournir un flux d’utilisateurs 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_addresses
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_4eC39HqLyjWDarjtT1zdp7dc
La réponse :
{ "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_addresses
: adresse de portefeuille suggérée pour l’envoi de cryptomonnaies (la sélection par défaut sur l’écran du portefeuille)lock_wallet_address
: indique si l’adresse de portefeuille suggérée doit être verrouillée ou nonsource_currency
: monnaie fiduciaire de la transaction (usd
uniquement pour le moment)source_amount
: montant en devise fiduciaire à utiliser pour l’achat de cryptomonnaies (cet attribut et le montant de destination s’excluent mutuellement)destination_network
: réseau de chiffrement par défaut pour cette rampe d’accès (par exemple,ethereum
)destination_currency
: cryptomonnaie par défaut pour cette session de rampe d’accès (par exemple,eth
)destination_amount
: quantité de cryptomonnaie à acheter (cet attribut et le montant source s’excluent mutuellement)destination_currencies
: table des cryptomonnaies auxquelles vous souhaitez vous limiter (par exemple,[eth, usdc]
)destination_networks
: table des réseaux de chiffrement auxquels vous souhaitez vous limiter (par exemple,[ethereum, polygon]
)
Reportez-vous à 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.
Comment 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 devront fournir au moins les informations suivantes :
- Prénom
- Nom
- 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_information
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_4eC39HqLyjWDarjtT1zdp7dc
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_information.email
: chaîne au format libre pour l’adresse e-mail de l’utilisateurcustomer_information.first_name
: chaîne au format libre pour le prénom de l’utilisateurcustomer_information.last_name
: chaîne au format libre pour le nom de famille de l’utilisateurcustomer_information.dob.year
: nombre entier pour l’année de naissance de l’utilisateurcustomer_information.dob.month
: nombre entier pour le mois de naissance de l’utilisateurcustomer_information.dob.day
: nombre entier pour le jour de naissance de l’utilisateurcustomer_information.address.country
: chaîne du code pays à deux lettres du pays de résidence de l’utilisateurcustomer_information.address.line1
: chaîne au format libre pour la première ligne de l’adresse de l’utilisateurcustomer_information.address.line2
: chaîne au format libre pour la deuxième ligne de l’adresse de l’utilisateurcustomer_information.address.city
: chaîne au format libre pour la ville de l’utilisateurcustomer_information.address.state
: 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 »customer_information.address.postal_code
: chaîne au format libre pour le code postal de l’utilisateur
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).
Gestion de 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 si un utilisateur peut être pris en charge
Comme précisé à la section Ensemble de fonctionnalités, la rampe d’accès n’est pour l’heure disponible qu’aux États-Unis.
Transmettez customer_ip_address
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_onramp_unsupportable_customer
si le client se trouve à un endroit que nous ne prenons pas en charge (selon sa customer_ip_address
).
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 un exemple 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_4eC39HqLyjWDarjtT1zdp7dc
{ "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." } }
Faire face aux attaques frauduleuses
Stripe fait office d’entité officielle et accepte la responsabilité en cas de litige et de fraude. Stripe possède 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 : Demande :
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u
: \sk_test_4eC39HqLyjWDarjtT1zdp7dc
Réponse (400) :
{ "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", // 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_payment
: 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.fulfillment_processing
: le client a finalisé son paiement. Nous n’avons pas encore envoyé la cryptomonnaie qu’il a achetée.fulfillment_complete
: le client a réglé la paiement de la cryptomonnaie et nous avons confirmé l’envoi.
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_sessions
Nom du paramètre | Saisissez (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 | Montant par défaut des monnaies fiduciaires (en décimales) à échanger en cryptomonnaies.
|
destination_networks | Tableau<String> (facultatif) par défaut : null | Liste des réseaux de cryptomonnaies de destination parmi lesquels l’utilisateur a le choix.
|
destination_currencies | Tableau<String> (facultatif) par défaut : null | La liste des cryptomonnaies de destination parmi lesquelles l’utilisateur peut choisir.
|
destination_network | Chaîne (facultatif) par défaut : null | Le 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 | 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_4eC39HqLyjWDarjtT1zdp7dc
{ "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_sessions/:id
Nom du paramètre | Saisissez (facultatif ?) par défaut : ? | Détails |
---|---|---|
Aucun paramètre n’est pris en charge pour cette opération ! |
Exemple de requête et de réponse :
curl -X GET https://api.stripe.com/v1/crypto/onramp_sessions/cos_0MYvv9589O8KAxCGPm84FhVR \ -u
:sk_test_4eC39HqLyjWDarjtT1zdp7dc
{ "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_onramp_disabled |
D’après le paramètre customer_ip_address , nous ne pouvons pas prendre en charge le client indiqué. | 400 | crypto_onramp_unsupported_country ou crypto_onramp_unsupportable_customer |
Une customer_ip_address mal formée est transmise au endpoint /v1/crypto/onramp_session . | 400 | customer_ip_address |
Les paramètres source_amount et destination_amount s’excluent mutuellement, mais ils sont tous les deux définis par la plateforme. | 400 | crypto_onramp_invalid_source_destination_pair |
L’un des paramètres destination_currency et destination_network est défini, mais pas l’autre | 400 | crypto_onramp_incomplete_destination_currency_and_network_pair |
La combinaison de destination_currency et destination_network n’est pas valide | 400 | crypto_onramp_invalid_destination_currency_and_network_pair |
Le paramètre source_amount est défini, mais pas source_currency | 400 | crypto_onramp_missing_source_currency |
La valeur de source_amount n’est pas un nombre positif | 400 | crypto_onramp_invalid_source_amount |
Le paramètre destination_amount est défini, mais pas destination_currency | 400 | crypto_onramp_missing_destination_currency |
La valeur de destination_amount n’est pas un nombre positif | 400 | crypto_onramp_invalid_destination_amount |
La combinaison de destination_currencies et destination_networks ne comporte aucune devise prise en charge | 400 | crypto_onramp_invalid_destination_currencies_and_networks |
La valeur de destination_currency ne figure pas dans le paramètre destination_currencies | 400 | crypto_onramp_conflicting_destination_currency |
La valeur de destination_network ne figure pas dans le paramètre destination_networks | 400 | crypto_onramp_conflicting_destination_network |
Au moins une des adresses de portefeuille figurant dans wallet_addresses est associée à un réseau qui n’apparaît pas dans le paramètre destination_networks | 400 | crypto_onramp_wallet_addresses_not_all_networks_supported |
Aucune adresse de portefeuille n’a été fournie dans wallet_addresses , alors que la valeur de lock_wallet_address est « true » | 400 | crypto_onramp_no_wallet_address_to_lock |
L’entreprise n’a pas défini les champs business_name ou business_url . Ceux-ci sont renseignés dans le Dashboard sous Public business name et Business website | 400 | crypto_onramp_merchant_not_properly_setup |
Récupérer plusieurs sessions
Endpoint: GET /v1/crypto/onramp_sessions
Récupérez plusieurs sessions de rampe d’accès en même temps à l’aide de l’endpoint de listage.
Webhooks
Nous envoyons un webhook crypto.onramp_session_updated
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.
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 à l’aide des 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 le notifier lorsqu’un précédent achat de rampe d’accès a été traité. Pour cette raison, l’objet OnrampSession est avec état et 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 client est un identifiant unique pour la session de la rampe dation 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.