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 installieren
clientseitig
serverseitig

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.

onramp.html
<head>
  <title>Onramp</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
</head>

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

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 erstellen
serverseitig

Erstellen Sie eine Crypto-Onramp-Sitzung, indem Sie den folgenden curl-Befehl in Ihrem Datenterminal ausführen:

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

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äche
clientseitig

Importieren Sie sowohl das StripeJS- als auch das OnrampJS-Paket:

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Crypto Onramp</title>
    <meta name="description" content="A demo of the hosted onramp" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="https://js.stripe.com/basil/stripe.js"></script>
    <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
    <script src="onramp.js" defer></script>
  </head>
  <body>
    <div id="onramp-element" />
  </body>
</html>

Verwenden Sie das client_secret aus Ihrem serverseitigen Aufruf im vorherigen Schritt, um die Onramp-Sitzung zu initiieren und bereitzustellen:

onramp.js
const stripeOnramp = StripeOnramp("pk_test_TYooMQauvdEDq54NiTphI7jx"
);
initialize();
// Initialize the onramp element with a client secret
function initialize() {
  // IMPORTANT: replace the following with your logic of how to mint/retrieve the client secret
  const clientSecret = "cos_1Lb6vsAY1pjOSNXVWF3nUtkV_secret_8fuPvTzBaxj3XRh14C6tqvdl600rpW7hG4G";
  const onrampSession = stripeOnramp.createSession({clientSecret});
  onrampSession
    .mount("#onramp-element");
}

Nach der Ausführung des Skripts rendert Onramp das folgende Dialogfeld:

Einbettung der Fiat-zu-Krypto-Onramp von Stripe in eine Drittanbieteranwendung

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 und address_full_match für die Adresszeile 1.
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_secret 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.

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_secret aus der URL und stellt die Onramp-Nutzeroberfläche bereit:

onramp.js
const stripeOnramp = StripeOnramp(pk_test_TYooMQauvdEDq54NiTphI7jx
);
initialize();
// initialize onramp element with client secret
function initialize() {
  const url = window.location.href.replace(/\/$/, '');
  const clientSecret = url.substring(url.lastIndexOf('/') + 1);
  const onrampSession = stripeOnramp.createSession({
    clientSecret,
    // other client side options that customize the look and feel
  });
  onrampSession
    .addEventListener('onramp_session_updated', handleSessionUpdate)
    .mount("#onramp-element");
}
function handleSessionUpdate(event) {
  const session = event.payload.session;
  if (session.status === 'fulfillment_complete' || session.status === 'rejected') {
    // redirect back to mobile app through universal link
    window.location.assign('/onramp_success/' + session.id);
  }
}

Konfigurieren Sie universelle Links, um /onramp_success zurück zu Ihrer mobilen App per Deep-Link zu verlinken. Erwägen Sie, eine Ausweich- oder onramp_success-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_details 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_processing übergeht. Sie können den Nutzer/innen gestatten, den Rest Ihrer Anwendung zu erkunden, während sie im Hintergrund den Status der OnrampSession abfragen.