Onramp API-DokumentationÖffentliche Vorschau
Verwenden Sie die Onramp API-Dokumentation, wenn Sie die einbettbare Onramp erstellen.
Beachten Sie beim Erstellen Ihrer Onramp-Integration die folgenden Entwicklerabläufe.
Onramp in Ihre Anwendung integrieren
Bevor Sie den Live-Modus verwenden können, muss Stripe Ihren Onramp-Antrag genehmigen.
Jetzt starten
So vernetzen Sie eine Anwendung mit der Onramp:
Nach dem Onboarding bei Stripe verwenden Sie das Dashboard, um Ihre geheimen and publishable API-Schlüssel abzurufen.
Generieren Sie eine serverseitige
CryptoOnrampSession.Stellen Sie auf dem Server einen neuen API-Endpoint bereit (zum Beispiel
myserver.), der den Stripe-Endpointcom/mint-onramp-session POST /v1/crypto/onramp_aufruft. Dadurch wird eine Onramp-Sitzung mit Stripe „geprägt“ (Minting), die Sie mit neuen oder wiederkehrenden Nutzern/Nutzerinnen verwenden können. Sie müssen das Minting einer Sitzung pro Nutzer/in durchführen.sessions Führen Sie folgenden Befehl aus:
Command Linecurl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u:sk_test_BQokikJOvBiI2HlWgH4olfQ2Sie erhalten eine Antwort ähnlich der folgenden:
{ "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. Lesen Sie den Abschnitt zur Unterstützbarkeit weiter unten, um zu erfahren, warum dies passieren kann. Wir empfehlen, dass Sie die Onramp-Komponente bedingt rendern, wen ein/e Nutzer/in während der Sitzungserstellung einen HTTP-Status
200erhält, um eine Fallback-Nutzeroberfläche bereitzustellen, die mit Sitzungserstellungsfehlern umgehen kann.
Das client_secret der Sitzung im Frontend verwenden
Um die Onramp-Komponente zu initialisieren, benötigen Sie:
- Ihr veröffentlichbarer API-Schlüssel.
- Das
client_aus Ihrer Anfrage ansecret POST /v1/crypto/onramp_.sessions
Der folgende Code stellt einen iframe auf dem Knoten #onramp-element bereit, der die gesamte Onramp hostet. Sie können einen Ereignis-Listener verwenden, um die Funktionalität Ihrer Anwendung zu verbessern. Beispielsweise können Sie den Betrieb in einer dezentralen Anwendung (Dapp) nach dem Kauf von Kryptowährungen wieder aufnehmen. Sehen Sie sich die Frontend-Ereignisse für alle Ereignisse an, die ein/e Nutzer/in abonnieren kann.
<!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"
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_ erfassen, wird das CryptoOnrampSession-Objekt entsprechend aktualisiert. Webhooks und Frontend-Ereignisse 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.
Transaktionsparameter vorab ausfüllen
Um einen nahtlosen Onramp-Nutzerablauf bereitzustellen, können Sie einige der Parameter der Onramp-Sitzung vorab ausfüllen. Zum Beispiel hätte eine Dapp oder Wallet bereits die wallet_ eines Nutzers/einer Nutzerin. 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_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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_: Die vorgeschlagene Wallet-Adresse, an die Kryptowährungen gesendet werden sollen (die Standardauswahl auf dem Bildschirm zum Anhängen der Wallet)addresses lock_: Ob die vorgeschlagene Wallet-Adresse gesperrt werden soll oder nichtwallet_ address source_: Die Fiat-Währung für die Transaktion (derzeit nurcurrency usdundeur)source_: 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)amount destination_: Das Standard-Kryptonetzwerk für diese Onramp (z. B.network ethereum)destination_: Die Standard-Kryptowährung für diese Onramp-Sitzung (z. B.currency eth).destination_: Der Betrag der Kryptowährung, die gekauft wird (dieser und der Quellbetrag schließen sich gegenseitig aus)amount destination_: Ein Array von Kryptowährungen, auf die Sie die Auswahl beschränken möchten (z. B.currencies [eth, usdc])destination_: Ein Array von Krypto-Netzwerken, auf die Sie die Auswahl beschränken möchten (z. B.networks [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.
Kundeninformationen vorab ausfüllen
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.
Während des gesamten Ablaufs müssen die Nutzer/innen mindestens Folgendes angeben:
- Vorname
- Nachname
- Geburtsdatum
- SSN
- 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_ 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_BQokikJOvBiI2HlWgH4olfQ2
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_– Freiform-Zeichenfolge für die E-Mail-Adresse des Nuzers/der Nutzerininformation. email customer_– Freiform-Zeichenfolge für den Vornamen des Nutzers/der Nutzerininformation. first_ name customer_– Freiform-Zeichenfolge für den Nachnamen des Nutzers/der Nutzerininformation. last_ name customer_– Ganzzahl für das Geburtsjahr des Nutzers/der Nutzerininformation. dob. year customer_– Ganzzahl für den Geburtsmonat des Nutzers/der Nutzerininformation. dob. month customer_– Ganzzahl für den Geburtstag des Nutzers/der Nutzerininformation. dob. day customer_– Zeichenfolge des zweistelligen Ländercodes für das Wohnsitzland des Nutzers/der Nutzerininformation. address. country customer_– Freiform-Zeichenfolge für die erste Adresszeile des Nutzers/der Nutzerininformation. address. line1 customer_– Freiform-Zeichenfolge für die zweite Adresszeile des Nutzers/der Nutzerininformation. address. line2 customer_– Freiform-Zeichenfolge für die Stadt des Nutzers/der Nutzerininformation. address. city customer_– Zeichenfolge des aus zwei Buchstaben bestehenden Codes für US-Bundesstaaten (der vollständige Name des Bundesstaates funktioniert auch), z. B. „CA“ oder „Kalifornien“information. address. state customer_– Freiform-Zeichenfolge für die Postleitzahl des Nutzers/der Nutzerininformation. address. postal_ code
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 Nutzerfreundlichkeit und Betrug
Stripe erzwingt Einschränkungen für das Onramp-Produkt sowohl im Hinblick auf die Nutzerfreundlichkeit als auch im Falle von Betrugsangriffen.
Die Nutzerfreundlichkeit überprüfen
Regionale AspekteVereinigte StaatenEU
Onramp ist nur in den USA (außer Hawaii) und in EU-Ländern verfügbar.
Übergeben Sie customer_ während der Sitzungserstellung, damit wir die oben genannten Einschränkungen vorbeugend überprüfen können. Der Endpoint gibt HTTP 400 mit code=crypto_ zurück, wenn sich der Kunde/die Kundin in einer Region befindet, die wir nicht unterstützen können (basierend auf customer_).
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_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." } }
Betrugsangriffe abwehren
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:
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \ -u: \sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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-Dokumentation
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", "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" }
CryptoOnrampSession-Zustandsmaschine
Das Feld status stellt eine Zustandsmaschine für die Sitzung mit den folgenden Status dar:
initialized: Die Anwendung hat das Minting der Onramp-Sitzung auf dem Server neu durchgeführt, aber der Kunde/die Kundin 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 Kunden/die Kundin aus irgendeinem Grund abgelehnt (KYC-Fehler, Probleme bei der Sanktionsprüfung, Betrugsprüfungen).requires_: Der/die Nutzer/in hat das Onboarding oder die Anmeldung abgeschlossen und wechselt zur Zahlungsseite. Wenn der Zahlungsversuch fehlschlägt, verbleibt dieser Status.payment fulfillment_: Der Kunde/die Kundin hat die Zahlung erfolgreich abgeschlossen. Wir haben die von ihnen gekaufte Kryptowährung noch nicht geliefert.processing fulfillment_: Der Kunde/die Kundin konnte erfolgreich für Kryptowährungen bezahlen und wir haben die Lieferung bestätigt.complete
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
Endpunkt: POST /v1/crypto/onramp_
| Parametername | Typ (optional?) Standardwert: ? | Details |
|---|---|---|
| wallet_addresses | Zeichenfolge (optional) Standard: null | Die Adresse der Krypto-Wallet des Endkunden/der Endkundin (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 Kunden/der Kundin, deren Onramp die Plattform vornehmen möchte. Wenn sich die IP des Nutzers/der Nutzerin 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 Onramp-Option 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_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 } } }
Sitzung abrufen
Endpoint: GET /v1/crypto/onramp_
| Parametername | Typ (optional?) Standardwert: ? | Details |
|---|---|---|
| Für diesen Vorgang werden keine Parameter unterstützt! |
Nachfolgend finden Sie ein Beispiel für eine Anfrage:
curl -X GET https://api.stripe.com/v1/crypto/onramp_sessions/cos_0MYvv9589O8KAxCGPm84FhVR \ -u:sk_test_BQokikJOvBiI2HlWgH4olfQ2
Sie erhalten eine Antwort ähnlich der folgenden:
{ "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-Status | Fehlercode |
|---|---|---|
| Aufgrund eines Vorfalls ist es uns nicht möglich, das Minting neuer Sitzungen durchzuführen | 400 | crypto_ |
Basierend auf dem Parameter customer_ können wir den/die angegebene/n Verbraucher/in nicht unterstützen. | 400 | crypto_ oder crypto_ |
Es wird eine fehlerhafte customer_ an den Endpoint /v1/crypto/onramp_ übergeben | 400 | customer_ |
source_ und destination_ schließen sich gegenseitig aus, die Plattform legt jedoch beide Werte fest. | 400 | crypto_ |
Eine der Optionen destination_ und destination_ ist festgelegt, die andere nicht | 400 | crypto_ |
Die Kombination aus destination_ und destination_ ist ungültig | 400 | crypto_ |
source_ ist festgelegt, aber source_ ist nicht festgelegt | 400 | crypto_ |
source_ ist keine positive Zahl | 400 | crypto_ |
destination_ ist festgelegt, aber destination_ ist nicht festgelegt | 400 | crypto_ |
destination_ ist keine positive Zahl | 400 | crypto_ |
Die Kombination aus destination_ und destination_ hat keine unterstützten Währungen | 400 | crypto_ |
destination_ ist nicht in destination_ enthalten | 400 | crypto_ |
destination_ ist nicht in destination_ enthalten | 400 | crypto_ |
Mindestens eine Wallet-Adresse in wallet_ ist mit einem Netzwerk verknüpft, das nicht in destination_ enthalten ist. | 400 | crypto_ |
Unter wallet_ wurden keine Wallet-Adressen angegeben, aber lock_ wurde auf true gesetzt | 400 | crypto_ |
Das Unternehmen hat die Felder business_ oder business_ nicht festgelegt. Diese werden im Dashboard unter Public business name and Business website ausgefüllt | 400 | crypto_ |
Mehrere Sitzungen abrufen
Endpoint: GET /v1/crypto/onramp_
Rufen Sie mehrere Onramp-Sitzungen gleichzeitig mit dem Listen-Endpoint ab.
Webhooks
Wir senden jedes Mal den Webhook crypto., 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 Dashboard konfigurieren.
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-Ereignisse
Hier ist die Liste der Frontend-Ereignisse, 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 Nutzers/einer Nutzerin 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/der Kundin 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.