Verwendung der APIBeta
Beachten Sie beim Erstellen Ihrer Onramp-Integration die folgenden Entwicklerabläufe.
So integrieren Sie onramp in Ihre Anwendung
Für die Integration einer Anwendung zur Nutzung von Onramp ist Folgendes erforderlich:
- Onboard zu Stripe und API-Schlüssel erhalten
Gehen Sie zum Dashboard und holen Sie sich:
- Der geheime Schlüssel, den Sie benötigen, um von einem von Ihnen kontrollierten Server API-Aufrufe an Stripe vorzunehmen
- Der veröffentlichbare Schlüssel, den Sie für Anfragen von Ihrem Frontend-Client verwenden
- Generieren Sie eine CryptoOnrampSession auf dem Server
Notiz
Ihr Onramp-Antrag muss zuerst genehmigt werden, damit Zugang zum Live-Modus gewährt werden kann. Erfahren Sie mehr über das Einreichen eines Antrags oder überprüfen Sie den Status Ihres Antrags auf der Onboarding-Seite.
Stellen Sie auf einem von Ihnen kontrollierten Server einen neuen API-Endpoint bereit (zum Beispiel myserver.com/mint-onramp-session
), der den Stripe-Endpoint POST /v1/crypto/onramp_sessions
aufruft. Dies “prägt” eine Onramp-Sitzung mit Stripe, die Sie mit neuen oder wiederkehrenden Benutzern verwenden können. Sie müssen eine Sitzung pro Benutzer prägen.
Die Anfrage:
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u
:sk_test_4eC39HqLyjWDarjtT1zdp7dc
Die Antwort:
{ "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 } }
Dieser Endpoint gibt Fehlercodes zurück, wenn Stripe keine Onramp-Sitzungen erstellen kann. Warum dies der Fall sein könnte, erfahren Sie im nachfolgenden Abschnitt zur Supportfähigkeit.
Notiz
Für eine optimale Nutzererfahrung rendern Sie die onramp-Komponente bedingt, wenn ein/e Nutzer/in während der Sitzungserstellung den HTTP-Status 200
erhält, und stellen Sie eine Ausweich- Nutzeroberfläche bereit, die Fehler bei der Sitzungserstellung handhabt.
- Sitzung client_secret im Frontend verwenden
Um die onramp-Komponente zu initialisieren, benötigen Sie Folgendes:
- Ihr veröffentlichbarer API-Schlüssel aus Schritt 1
- Das client_secret aus Ihrer Anfrage an
POST /v1/crypto/onramp_sessions
in Schritt 2 oben
<!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"
Der obige Code stellt einen iframe auf dem #onramp-element
-Knoten bereit, der die gesamte onramp hostet. Sie können einen Ereignis-Listener verwenden, um das Nutzererlebnis zu verbessern – zum Beispiel, um den Betrieb in einer Dapp nach Krypto-Käufen wiederaufzunehmen (siehe den Abschnitt Frontend-Ereignisse für alle Ereignisse, die abonniert werden können).
- Das CryptoOnramp-Element wird gerendert und übernommen
Nachdem das obige CryptoOnramp
-HTML-Element gerendert wurde, steuert der Frontend-Client die Schnittstelle. Wenn sich der Status der Sitzung ändert und wir mehr Details zu transaction_details
erfassen, wird das CryptoOnrampSession
-Objekt entsprechend aktualisiert. Webhooks und Frontend-Events werden für jeden auftretenden Statusübergang generiert. Durch die Verwendung von Frontend-Event-Listener können Sie Nutzer/innen nach Abschluss der onramp-Sitzung zurück zu Ihrem Anwendungs-Nutzerablauf umleiten.
- (Optional) Ändern Sie das Erscheinungsbild der Onramp
Um den Dunkelmodus zu aktivieren, fügen Sie eine Appearance-Struktur in den obigen Aufruf zur Sitzungserstellung ein.
const onrampSession = stripeOnramp.createSession({ clientSecret: clientSecret, appearance: { theme: 'dark' }, });
Wenn Sie das Erscheinungsbild nicht angeben, wird für onramp standardmäßig ein helles Design verwendet. Sie können das Design auch ändern, nachdem onramp gerendert wurde, indem Sie Folgendes aufrufen:
onrampSession.setAppearance({ theme: newTheme });
Sie können Branding-Einstellungen verwenden, um Ihr Logo und Ihre Markenfarben hochzuladen, die automatisch für Onramp-Sitzungen gelten, die mit Ihrem Plattform-API-Schlüssel erstellt wurden.
Wie man Transaktionsparameter vorausfüllt
Um einen nahtlosen Nutzerablauf bei onramp bereitzustellen, können Sie einige der Parameter der onramp-Sitzung vorab ausfüllen. Zum Beispiel hätte eine Dapp oder Wallet bereits die wallet_addresses
eines/einer Nutzer/in. Dies können Sie während der Sitzungserstellung wie folgt erreichen:
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
Die Antwort:
{ "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 } } }
Die folgenden Parameter können vorab ausgefüllt werden:
wallet_addresses
: Die vorgeschlagene Wallet-Adresse, an die Kryptowährungen gesendet werden sollen (die Standardauswahl auf dem Bildschirm zum Anhängen der Wallet)lock_wallet_address
: Ob die vorgeschlagene Wallet-Adresse gesperrt werden soll oder nichtsource_currency
: Die Fiat-Währung der Transaktion (derzeit nurusd
)source_amount
: Der Betrag der Fiat-Währung, der für den Kauf von Kryptowährungen verwendet werden soll (dieser und der Zielbetrag schließen sich gegenseitig aus)destination_network
: Das Standard-Kryptonetzwerk für diese Onramp (z. B.ethereum
)destination_currency
: Die Standard-Kryptowährung für diese Onramp-Sitzung (z. B.eth
).destination_amount
: Der Betrag der Kryptowährung, die gekauft wird (dieser und der Quellbetrag schließen sich gegenseitig aus)destination_currencies
: Ein Array von Kryptowährungen, auf die Sie die Auswahl beschränken möchten (z. B.[eth, usdc]
)destination_networks
: Ein Array von Krypto-Netzwerken, auf die Sie die Auswahl beschränken möchten (z. B.[ethereum, polygon]
)
In der API-Dokumentation finden Sie weitere Details zu den spezifischen Anforderungen und wie sie sich auf die Nutzer/innen in der onramp- Nutzeroberfläche auswirken.
So füllen Sie Kundeninformationen vorab aus
Um einen möglichst reibungslosen Ablauf für die Nutzer/innen während des Einführungsprozesses zu ermöglichen und die Konversion zu erhöhen, können Sie einige der erforderlichen KYC-Informationen für die Nutzer/innen vorab eingeben, wenn sie diese bereits in Ihrer Anwendung erfasst haben.
Im gesamten Ablauf müssen die Nutzer/innen mindestens Folgendes angeben:
- Vorname
- Nachname
- Geburtsdatum
- IdNr
- Privatadresse (Land, Adresszeile 1, Adresszeile 2, Ort, Bundesland, Postleitzahl)
Die Onramp API bietet die Möglichkeit, alle diese Felder mit Ausnahme von SSN vorab auszufüllen. Um diese Informationen vorab auszufüllen, können Sie sie mit dem Parameter customer_information
in der API zur OnrampSession-Erstellung angeben.
Beispielanfrage:
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
Antwort:
{ "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 } }
Die folgenden Parameter können vorab ausgefüllt werden:
customer_information.email
– Freiform-Zeichenfolge für die E-Mail-Adresse des/der Nutzers/incustomer_information.first_name
– Freiform-Zeichenfolge für den Vornamen des/der Nutzers/incustomer_information.last_name
– Freiform-Zeichenfolge für den Nachnamen des/der Nutzers/incustomer_information.dob.year
– Ganzzahl für das Geburtsjahr des/der Nutzers/incustomer_information.dob.month
– Ganzzahl für den Geburtsmonat des/der Nutzers/incustomer_information.dob.day
– Ganzzahl für den Geburtstag des/der Nutzers/incustomer_information.address.country
– Zeichenfolge des zweistelligen Ländercodes für das Wohnsitzland des/der Nutzers/incustomer_information.address.line1
– Freiform-Zeichenfolge für die erste Adresszeile des/der Nutzers/incustomer_information.address.line2
– Freiform-Zeichenfolge für die zweite Adresszeile des/der Nutzers/incustomer_information.address.city
– Freiform-Zeichenfolge für die Stadt des/der Nutzers/incustomer_information.address.state
– Zeichenfolge des aus zwei Buchstaben bestehenden Codes für US-Bundesstaaten (der vollständige Name des Bundesstaates funktioniert auch), z. B. „CA“ oder „Kalifornieen“customer_information.address.postal_code
– Freiform-Zeichenfolge für die Postleitzahl des/der Nutzers/in
Alle Felder sind optional, und Sie können eine beliebige Teilmenge davon für die Vorabausfüllung angeben. Wenn Sie jedoch Ihr Geburtsdatum angeben, müssen Sie auch year
, month
und day
angeben (d. h. nicht nur ein oder zwei der Felder für den Geburstag).
Umgang mit Benutzerfreundlichkeit und Betrug
Stripe erzwingt Einschränkungen für das Produkt onramp sowohl im Hinblick auf die Nutzerfreundlichkeit als auch im Falle von Betrugsangriffen.
Prüfen, ob ein/e Nutzer/in unterstützt werden kann
Wie im Abschnitt Feature Set erwähnt, ist die Onramp derzeit nur in den USA verfügbar.
Übergeben Sie customer_ip_address
während der Sitzungserstellung, damit wir die oben genannten Einschränkungen vorbeugend überprüfen können. Der Endpoint gibt HTTP 400
mit code=crypto_onramp_unsupportable_customer
zurück, wenn sich der Kunde/die Kundin in einer Region befindet, die wir nicht unterstützen können (basierend auf customer_ip_address
).
In diesem Fall möchten Sie möglicherweise die Option Onramp für die Nutzer/innen ausblenden. Andernfalls wird unsere Onramp-Nutzeroberfläche im Status disabled
gerendert.
Nachfolgend finden Sie eine Beispielanfrage und -antwort (400), die dieses Verhalten veranschaulichen:
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." } }
Umgang mit Betrugsangriffen
Stripe fungiert als verantwortliches Unternehmen und übernimmt die Haftung für Anfechtungen und Betrug. Stripe verfügt über umfassendes Fachwissen im Risikomanagement, aber wir könnten beschließen, die Erstellung von Onramp-Sitzungen vorübergehend einzuschränken, wenn wir eine Situation mit hohem Risiko feststellen (z. B. wenn wir aktive Angriffe und Exploits sehen).
Wenn wir die API aufgrund eines unbeschränkten Betrugsangriffs schließen müssen, geben wir Folgendes zurück, wenn jemand versucht, eine neue Sitzung zu erstellen: Anfrage:
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u
: \sk_test_4eC39HqLyjWDarjtT1zdp7dc
Antwort (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 } }
API-Referenz
CryptoOnrampSession-Ressource
Die Ressource CryptoOnrampSession
sieht wie folgt aus:
{ "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" }
CryptoOnrampSession-Zustandsmaschine
Das Feld status
stellt eine Zustandsmaschine für die Sitzung mit den folgenden Status dar:
initialized
– Die Anwendung hat die Onramp-Sitzung auf dem Server neu erstellt, aber der/die Kund/in hat sie noch nicht verwendet. Die Sitzungen befinden sich in diesem Status, bis der/die Nutzer/in das Onboarding startet und zur Zahlung bereit ist.rejected
– Wir haben den/die Kund/in aus irgendeinem Grund abgelehnt (KYC-Fehler, Probleme bei der Sanktionsprüfung, Betrugsprüfungen).requires_payment
– Der/die Nutzer/in hat das Onboarding oder die Anmeldung abgeschlossen und wechselt zur Zahlungsseite. Wenn der Zahlungsversuch fehlschlägt, verbleibt dieser Status.fulfillment_processing
: Der/die Kund/in hat die Zahlung erfolgreich abgeschlossen. Wir haben die von ihnen gekaufte Kryptowährung noch nicht geliefert.fulfillment_complete
– Der/die Kund/in konnte erfolgreich für Kryptowährungen bezahlen und wir haben die Lieferung bestätigt.
CryptoOnrampSession-Vorgänge
Alle Endpoints erfordern eine Authentifizierung mit Ihrem API-Schlüssel. Der Authentifizierungs-Header wird in den Beispielanfragen weggelassen.
Anwendungen können die folgenden Vorgänge in einer CryptoOnrampSession
ausführen:
- Sitzung erstellen
- Eine bestehende Sitzung abrufen
Sitzung erstellen
Endpoint: POST /v1/crypto/onramp_sessions
Parametername | Typ (optional?) Standardwert: ? | Details |
---|---|---|
wallet_addresses | Zeichenfolge (optional) Standard: null | Die Adresse der Krypto-Wallet des Endkund/innen (für jedes Netzwerk), die für diese Transaktion verwendet werden soll.
Für Assets, die Ziel-Tags oder Memos verwenden, können Sie eine |
source_currency | Zeichenfolge (optional) Standard: null | Die Standard-Fiat-Währung der Quelle für die Onramp-Sitzung.
|
source_amount | Zeichenfolge (optional) Standard: null | Der Standardbetrag von Fiat (in Dezimalzahlen), der in Kryptowährungen umgewandelt werden soll.
|
destination_networks | Array<String> (optional) Standardwert: null | Die Liste der Krypto-Zielnetzwerke, aus denen der/die Nutzer/in wählen kann.
|
destination_currencies | Array<String> (optional) Standardwert: null | Die Liste der Ziel-Kryptowährungen, aus denen ein/e Nutzer/in wählen kann.
|
destination_network | Zeichenfolge (optional) Standard: null | Das standardmäßige Krypto-Zielnetzwerk.
|
destination_currency | Zeichenfolge (optional) Standard: null | Die Standard-Ziel-Kryptowährung.
|
destination_amount | Zeichenfolge (optional) Standard: null | Der Standardbetrag der Kryptowährung, in die getauscht werden soll.
|
customer_ip_address | Zeichenfolge (optional) Standard: null | Die IP-Adresse des/der Kund/in, deren Onrampe die Plattform vornehmen möchte. Wenn sich die IP des/der Nutzer/in in einer Region befindet, die wir nicht unterstützen können, geben wir HTTP 400 mit einem entsprechenden Fehlercode zurück. Wir unterstützen IPv4- und IPv6-Adressen. Die geografische Unterstützung wird später im Onramp-Ablauf erneut überprüft. So kann die Option Onramp für eine bessere Nutzererfahrung für nicht berechtigte Nutzer/innen ausgeblendet werden. |
Beispielanfrage und -antwort:
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 } } }
Sitzung abrufen
Endpoint: GET /v1/crypto/onramp_sessions/:id
Parametername | Typ (optional?) Standardwert: ? | Details |
---|---|---|
Keine unterstützten Parameter für diesen Vorgang! |
Beispielanfrage und -antwort:
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 } } }
Validierung und Fehler
Bedingung | HTTP-Fehlerstatus | Fehlercode |
---|---|---|
Wir können aufgrund eines Vorfalls keine neuen Sitzungen erstellen | 400 | crypto_onramp_disabled |
Aufgrund der Parameter customer_ip_address können wir den angegebenen Kunden/die angegebene Kundin nicht unterstützen. | 400 | crypto_onramp_unsupported_country oder crypto_onramp_unsupportable_customer |
Es wird eine fehlerhafte customer_ip_address an den Endpoint /v1/crypto/onramp_session übergeben | 400 | customer_ip_address |
source_amount und destination_amount schließen sich gegenseitig aus, die Plattform legt jedoch beide Werte fest. | 400 | crypto_onramp_invalid_source_destination_pair |
Eine der Optionen destination_currency und destination_network ist festgelegt, die andere nicht | 400 | crypto_onramp_incomplete_destination_currency_and_network_pair |
Die Kombination aus destination_currency und destination_network ist ungültig | 400 | crypto_onramp_invalid_destination_currency_and_network_pair |
source_amount ist festgelegt, aber source_currency ist nicht festgelegt | 400 | crypto_onramp_missing_source_currency |
source_amount ist keine positive Zahl | 400 | crypto_onramp_invalid_source_amount |
destination_amount ist festgelegt, aber destination_currency ist nicht festgelegt | 400 | crypto_onramp_missing_destination_currency |
destination_amount ist keine positive Zahl | 400 | crypto_onramp_invalid_destination_amount |
Die Kombination aus destination_currencies und destination_networks hat keine unterstützten Währungen | 400 | crypto_onramp_invalid_destination_currencies_and_networks |
destination_currency ist nicht in destination_currencies enthalten | 400 | crypto_onramp_conflicting_destination_currency |
destination_network ist nicht in destination_networks enthalten | 400 | crypto_onramp_conflicting_destination_network |
Mindestens eine Wallet-Adresse in wallet_addresses ist mit einem Netzwerk verknüpft, das nicht in destination_networks enthalten ist. | 400 | crypto_onramp_wallet_addresses_not_all_networks_supported |
Unter wallet_addresses wurden keine Wallet-Adressen angegeben, aber lock_wallet_address wurde auf true gesetzt | 400 | crypto_onramp_no_wallet_address_to_lock |
Das Unternehmen hat die Felder business_name oder business_url nicht festgelegt. Diese werden im Dashboard unter Public business name and Business website ausgefüllt | 400 | crypto_onramp_merchant_not_properly_setup |
Mehrere Sitzungen erhalten
Endpoint: GET /v1/crypto/onramp_sessions
Rufen Sie mehrere Onramp-Sitzungen gleichzeitig mit dem Listen-Endpoint ab.
Webhooks
Wir senden jedes Mal den Webhook crypto.onramp_session_updated
, wenn sich der Status einer Onramp-Sitzung nach der Erstellung ändert. Wir senden keine, wenn eine neue Sitzung erstellt wird. Sie können Webhooks im Dashboardkonfigurieren.
Die vom Webhook verwendete Ressource ist die obige CryptoOnrampSession
:
{ "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 } } } } }
Frontend-Events
Hier ist die Liste der Frontend-Events, die Sie abonnieren können:
// 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}, }
Wie oben gezeigt, können Ereignisse mit den Standardfunktionen addEventListener/removeEventListener
über OnrampSession abonniert und abgemeldet werden. Sie können '*'
verwenden, um alle Ereignisse zu erfassen.
Sitzungspersistenz
Sie können die Sitzungspersistenz verwenden, um Benachrichtigungen bereitzustellen und Nutzer/innen nach dem Kauf mit der Onramp einzubinden.
Vorteile der Sitzungspersistenz
In einigen Fällen möchten Sie möglicherweise eine Onramp-Sitzung über mehrere Nutzerbesuche hinweg beibehalten. Wenn beispielsweise die Onramp-Sitzung eines/einer Nutzer/in unterbrochen wird, können Sie diese/n dazu auffordern und Möglichkeiten anbieten, die Onramp-Sitzung zu einem späteren Zeitpunkt wiederaufzunehmen. Wenn ein/e Nutzer/in die Seite nach Abschluss der Zahlung aktualisiert, können Sie sie/ihn auch weiterhin benachrichtigen, wenn ein früherer Onramp-Kauf getätigt wurde. Aus diesem Grund ist das OnrampSession-Objekt zustandsbehaftet und wird als serverseitige Ressource gespeichert. Durch Initialisieren der Onramp-Nutzeroberfläche mit einem zuvor verwendeten Client-Geheimnis der OnrampSession kehren die Nutzer/innen dort zurück, wo sie aufgehört haben.
Konfiguration der Sitzungspersistenz
Ein Client-Geheimnis ist eine eindeutige Kennung für die Onramp-Sitzung, die den Lebenszyklus einer Sitzung speichert, ohne sensible Zahlungsinformationen preiszugeben. Es werden jedoch private Informationen wie Wallet-Adressen preisgegeben. Sie dürfen nicht protokolliert, in URLs eingebettet oder Personen außer dem Kunden selbst zugänglich gemacht werden. Stellen Sie sicher, dass auf jeder Seite, die das Client-Geheimnis enthält, TLS angegeben ist. Wenn Sie eine Web2-ähnliche Kontostruktur haben, können Sie OnrampSession mit Ihrem Nutzerobjekt verknüpfen und nach der Authentifizierung abrufen. Bei einer kontenlosen Web3-Anwendung würde es zu Problemen für die Nutzer/innen kommen, wenn die Verwendung von Nachrichtensignaturen zur Authentifizierung erforderlich wäre. Lokaler Speicher, der die Privatsphäre schützt, sorgt für ein akzeptables Nutzererlebnis.