Richten Sie eine einbettbare Onramp-Integration einÖffentliche Vorschau
Verwenden Sie diesen Leitfaden, um die einbettbare Onramp vollständig anzupassen.
Bei diesem Leitfaden handelt es sich um eine erweiterte Version des QuickStarts für einbettbaren Onramp. Erfahren Sie, wie Sie weitere Funktionalitäten hinzufügen, wie z. B.:
- Installieren des SDK mit einem Skript-Tag oder Paket-Manager
- Geschätzte Angebote für Onramp-Umrechnungen in Kryptowährungen abrufen
- Onramp-Nutzeroberfläche in mobile Webansichten konfigurieren
SDK und Client-Bibliothek installierenclientseitigserverseitig
Clientseitig
Fügen Sie die folgenden Skripts mithilfe von Skript-Tags in das <head>
-Element Ihres HTML-Codes ein. Aus Kompatibilitätsgründen und aus Gründen der PCI-Konformität müssen diese Skripts immer direkt aus den Stripe-Domains (https://js.stripe.com und https://crypto-js.stripe.com) geladen werden. Fügen Sie die Skripts nicht in ein Paket ein und hosten Sie selbst keine Kopie. Wenn Sie dies tun, kann Ihre Integration ohne Vorwarnung unterbrochen werden.
<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>
Verwenden Sie das Onramp JS SDK als Modul
Verwenden Sie das npm-Paket, um das Onramp-JS-SDK als ES-Modul zu laden. Das Paket enthält Definitionen des Typescript-Typs.
npm install --save @stripe/stripe-js @stripe/crypto
Alternative SDK-Installation
Alternativ können Sie das clientseitige Stripe-Krypto-ES-Modul-SDK mit einem Skript-Tag oder Paket-Manager installieren. Das SDK umschließt die globale StripeOnramp
-Funktion, die vom Stripe-Kryptoskript als ES Modul bereitgestellt wird.
Laden Sie das Skript manuell. Fügen Sie die folgenden Skripte mithilfe von Skript-Tags in das
<head>
-Element Ihres HTML ein. Diese Skripte müssen stets direkt aus Stripes Domänen, https://js.stripe.com und https://crypto-js.stripe.com, aus Gründen der Kompatibilität und zur PCI-Compliance geladen werden. Fügen Sie die Skripte nicht in ein Paket ein und hosten Sie selbst keine Kopie. Wenn Sie dies tun, kann Ihre Integration ohne Warnung unterbrochen werden.<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>
Legen Sie den veröffentlichbaren API-Schlüssel fest, damit Stripe das von Ihrem Backend erstellte
OnrampSession
-Objekt abrufen kann. Beispiel:const stripeOnramp = StripeOnramp(
);'pk_test_TYooMQauvdEDq54NiTphI7jx'Um das Modul über den Paketmanager zu installieren, installieren Sie zunächst das Stripe.js-ES-Modul und das Stripe Krypto-ES-Modul aus dem öffentlichen npm-Verzeichnis. Das Paket enthält Typescript-Typdefinitionen.
Command Linenpm install @stripe/stripe-js @stripe/crypto
Importieren Sie das Modul und legen Sie den veröffentlichbaren API-Schlüssel fest, damit Stripe das von Ihrem Backend erstellte
OnrampSession
-Objekt abrufen kann. Die Funktion gibt einPromise
-Objekt zurück, das nach dem Laden der Skripts mit einem neu erstelltenStripeOnramp
-Objekt aufgelöst wird.import {loadStripeOnramp} from '@stripe/crypto'; const stripeOnramp = await loadStripeOnramp(
);'pk_test_TYooMQauvdEDq54NiTphI7jx'
Serverseitig
Unsere offiziellen Bibliotheken enthalten keine integrierte Unterstützung für die API-Endpoints, da sich die Onramp API in der eingeschränkten Betaphase befindet. Daher wird in unseren Beispielen curl für Backend-Interaktionen verwendet.
Eine Krypto-Onramp-Sitzung erstellenserverseitig
Erstellen Sie eine Crypto-Onramp-Sitzung, indem Sie den folgenden curl-Befehl in Ihrem Datenterminal ausführen:
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u
: \ -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" # add as many parameters as you'd likesk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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 } } }
In der Onramp-API-Dokumentation finden Sie die vollständige Parameterliste, die Sie beim Erstellen einer Sitzung übergeben können.
Rendern der Onramp Nutzeroberflächeclientseitig
Nach der Ausführung des Skripts rendert Onramp das folgende Dialogfeld:

Fiat-zu-Krypto-Onramp von Stripe, eingebettet in eine Drittanbieteranwendung
Sandbox-Werte
Achtung
Beträge für Sandbox-Transaktionen werden durch unsere vorab festgelegten Limits außer Kraft gesetzt.
Verwenden Sie die folgenden Werte, um eine Onramp-Transaktion in der Sandbox abzuschließen:
- Verwenden Sie auf dem OTP-Bildschirm
000000
für den Verifizierungscode. - Verwenden Sie auf dem Bildschirm mit den persönliche Daten
000000000
für die SSN undaddress_
für die Adresszeile 1.full_ match - Verwenden Sie auf dem Bildschirm mit den Zahlungsdetails die Test-Kreditkartennummer
4242424242424242
.
Integrationsnutzung anzeigen
Nachdem Sie Onramp gestartet haben, können Sie angepassten Nutzungsberichte im Stripe-Dashboard einsehen. Sie können auch zur Onboarding-Seite zurückkehren, um die Domains zu aktualisieren, auf denen Sie die Onramp hosten möchten. Dort können Sie auch den Status der Onboarding-Aufgaben prüfen.
OptionalDen Onramp für die mobile Nutzung konfigurieren
Erfahren Sie, wie Sie die Krypto-Onramp-Nutzeroberfläche von Stripe in mobile Webansichten und Browser integrieren können, indem Sie das Minting einer Sitzung durchführen, die Onramp-Nutzeroberfläche hosten, den Kauf abschließen und Nutzer/innen an die Mobil-App zurück leiten.
Minting einer Sitzung
Ähnlich wie bei anderen Integrationen müssen Sie einen Server-Endpoint implementieren, um für jeden Besuch eines Nutzers eine neue Onramp-Sitzung zuerstellen](/crypto/onramp/api-reference). Der Endpoint gibt ein client_
zurück, das die Onramp-Nutzeroberfläche laden oder einen Fehler anzeigen kann, wenn der Onramp nicht verfügbar ist.
Onramp-Nutzeroberfläche hosten
Erstellen Sie eine Frontend-Route (zum Beispiel www.my-web3-wallet.com/onramp/<client_secret>), um die Onramp-Nutzeroberfläche zu hosten. Ihr /onramp/<client_secret> verweist auf 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>
Dabei verwendet onramp.js das client_
aus der URL und stellt die Onramp-Nutzeroberfläche bereit:
const stripeOnramp = StripeOnramp(
); 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); } }pk_test_TYooMQauvdEDq54NiTphI7jx
Konfigurieren Sie universelle Links, um /onramp_
zurück zu Ihrer mobilen App per Deep-Link zu verlinken. Erwägen Sie, eine Ausweich- oder onramp_
-Seite bereitzustellen, um Nutzer/innen aufzufordern, manuell zurück zu Ihrer App zu wechseln.
Kauf abschließen
Wie bei einer Standardintegration steuert der Frontend-Client die gesamte Onramp-Nutzeroberfläche. Die Nutzeroberfläche passt sich der Bildschirmgröße an. Wenn sich der Sitzungsstatus ändert und wir mehr transaction_
erfassen, wird das CryptoOnrampSession
-Objekt entsprechend aktualisiert. Wir generieren Webhooks und Frontend-Ereignisse für jeden Statusübergang. Durch die Verwendung von Frontend-Ereignis-Listenern können Sie Nutzer/innen nach Abschluss der OnrampSession
wieder zu Ihrem Anwendungsablauf zurück leiten.
Zur Mobil-App weiterleiten
Über einen Deep-Link oder eine manuelle Umstellung können Nutzer/innen ihren Ablauf in Ihrer mobilen Anwendung wiederaufnehmen. Ihre Mobilanwendung kann Ihr Backend verwenden, um weiterhin den Status von CryptoOnrampSession
abzufragen.
Wenn ein/e Nutzer/in beispielsweise sein/ihr Guthaben bei der Ersteinrichtung aufstockt, können Sie sie/ihn zu Ihrer Anwendung zurückleiten, sobald die Sitzung in den Status fulfillment_
übergeht. Sie können den Nutzer/innen gestatten, den Rest Ihrer Anwendung zu erkunden, während sie im Hintergrund den Status der OnrampSession
abfragen.
OptionalKonversionsangebote konfigurieren
Mit der Onramp Quotes API können Plattformen geschätzte Angebote für Onramp-Konvertierungen in verschiedene Kryptowährungen in verschiedenen Netzwerken abrufen. Sie können einen festen Ausgangs- oder Zielbetrag angeben und die Angebote auf eine Untergruppe von Zielwährungen oder -netzwerken beschränken. Mit der API können Sie Angebote in der Nutzeroberfläche Ihres Produkts anzeigen, bevor die Nutzer/innen zum Onramp-Widget weitergeleitet werden. Wenn das Angebot abgelaufen ist, bevor der/die Nutzer/in das Onramp-Widget aufruft, wird dem Nutzer möglicherweise ein etwas anderes Angebot im Onramp-Widget angezeigt.
Konversionsangebot anfordern
Verwenden Sie den Endpoint GET /v1/crypto/onramp/quotes
, um ein Konversionsangebot zu erhalten. Die folgende Tabelle enthält alle verfügbaren Parameter für diesen Endpoint:
Parameter | Typ | Standard | Details |
---|---|---|---|
source_ | Zeichenfolge (optional) | usd | Der Währungscode ISO-4217. Wir unterstützen derzeit nur usd und eur . |
source_ | Zeichenfolge (optional) | 100,00 | Eine Zeichenfolgendarstellung des Fiat-Betrags, den Sie für den Onramp benötigen. Wenn source_ eingestellt ist, muss destination_ null sein (diese schließen sich gegenseitig aus, da Sie lediglich einen festen Betrag für ein Ende des Handels festlegen können). |
destination_ | Zeichenfolge (optional) | null | Eine Zeichenfolgendarstellung des Betrags der zu erwerbenden destination_ . Falls der destination_ festgelegt ist, muss der source_ null sein. Wenn Sie dieses Feld angeben, müssen Sie außerdem jeweils einen Wert für destination_ und destination_ festlegen. Dadurch wissen wir, für welche Kryptowährung ein Angebot gemacht werden soll.) |
destination_ | Array<String> (optional) | null
| Die Liste der Kryptowährungen, für die Sie Angebote generieren möchten. Wenn der Wert auf null gelassen wird, rufen wir Angebote für alle destination_ auf, die destination_ unterstützt.
|
destination_ | Array<String> (optional) | null
| Die Liste der Kryptowährungsnetzwerke, für die Sie quotes erstellen möchten. Wenn sie auf null gelassen wird, rufen wir Angebote für destination_ in allen Netzwerken ab.
|
Beispiel für Angebotsanfragen
Führen Sie den folgenden Befehl aus, um alle Währungsnetzwerk-Zielpaare mit einem Standard-Ausgangsbetrag von 100 USD abzurufen:
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \ -u
:sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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" }
Führen Sie den folgenden Befehl aus, um alle Währungsnetzwerk-Zielpaare mit einem Ausgangsbetrag von 200 USD abzurufen:
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \ -u
: \ -d "source_amount"="200"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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" }
Führen Sie den folgenden Befehl aus, um Angebote für ETH und SOL in den Ethereum- und Solana-Netzwerken abzurufen (das Ergebnis ist ETH auf Ethereum und SOL auf Solana). Wenn Sie destination_
und destination_
angeben, wird für jedes gültige Währungsnetzwerk-Paar ein Angebot ermittelt. Der Standardwert für destination_
ist alle Währungen und der Standardwert für destination_
ist alle Netzwerke.
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \ -u
: \ -d "source_amount"="200" \ -d "destination_currencies[]"="eth" \ -d "destination_currencies[]"="sol" \ -d "destination_networks[]"="ethereum" \ -d "destination_networks[]"="solana"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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" }
Führen Sie den folgenden Befehl aus, um Angebote für USDC auf Ethereum und Solana abzurufen:
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \ -u
: \ -d "source_amount"="200" \ -d "destination_currencies[]"="usdc" \ -d "destination_networks[]"="ethereum" \ -d "destination_networks[]"="solana"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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" }
Führen Sie den folgenden Befehl aus, um ein Angebot für ein einzelnes Währungsnetzwerk-Zielpaar (ETH auf Ethereum) mit dem angegebenen destination_
abzurufen:
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \ -u
: \ -d "destination_amount"="0.42" \ -d "destination_currencies[]"="eth" \ -d "destination_networks[]"="ethereum"sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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" }