組み込みオンランプの導入公開プレビュー

このガイドを使用して、埋め込み可能なオンランプを全面的にカスタマイズできます。

This guide is an extended version of the Embedded onramp quickstart. Learn to add more functionality such as how to:

Install the SDK using a script tag or package manager
Customize the onramp appearance
Configure the onramp UI into mobile web views
Handle customer supportability and fraud
Fetch estimated cryptocurrency conversion quotes

はじめに

The embedded onramp is only available in the EU and the US (excluding Hawaii).
The Onramp API is in public preview. You must submit the onramp application before you start development in a testing environment.
After you get access to the Onramp API, use the Dashboard to grab your secret and publishable API keys.

SDK およびクライアントライブラリをインストールする
クライアント側
サーバー側

クライアント側

Include the following scripts using script tags within the <head> element of your HTML. These scripts must always load directly from Stripe’s domains (https://js.stripe.com and https://crypto-js.stripe.com) for compatibility and PCI compliance.

Don’t include the scripts in a bundle or host a copy yourself because your integration might break without warning.

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

JS SDK

npm パッケージを使用して、オンランプ JS SDK を ES モジュールとして読み込みます。パッケージには、TypeScript の型定義が含まれています。

npm install --save @stripe/stripe-js @stripe/crypto

Alternative SDK installation

または、スクリプトタグまたはパッケージマネージャーを使用して、Stripe 暗号資産 ES モジュールのクライアント側 SDK をインストールできます。SDK は、Stripe 暗号資産スクリプトが提供するグローバル StripeOnramp 関数を ES モジュールとしてラップします。

スクリプトを手動で読み込みます。 内にスクリプトタグを使用して次のスクリプトを含めます。<head>HTML の要素。互換性とPCI 準拠のために、これらのスクリプトは常に Stripe のドメイン_https://js.stripe.com__と_https://crypto-js.stripe.com_,から直接読み込む必要があります。スクリプトをバンドルに含めたり、コピーを自身でホストしたりしないでください。含めると、警告なしに導入が中断される可能性があります。
```
<head>
  <title>Onramp</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
  <script src="https://crypto-js.stripe.com/crypto-onramp-outer.js"></script>
</head>
```
API 公開可能キーを設定し、バックエンドで作成した OnrampSession オブジェクトを Stripe が取得できるようにします。以下に例を示します。
```
const stripeOnramp = StripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');
```
パッケージマネージャーを使用してモジュールをインストールするには、まず npm 公開レジストリから Stripe.js ES モジュールと Stripe 暗号資産 ES モジュールをインストールします。パッケージには TypeScript 型定義が含まれています。
Command Line
```
npm install @stripe/stripe-js @stripe/crypto
```
モジュールをインポートし、API 公開可能キーを設定して、バックエンドで作成した OnrampSession オブジェクトを Stripe が取得できるようにします。この関数は、スクリプトの読み込み後に新しく作成された StripeOnramp オブジェクトによって解決される Promise オブジェクトを返します。
```
import {loadStripeOnramp} from '@stripe/crypto';

const stripeOnramp = await loadStripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');
```

サーバー側

Our official libraries don’t contain built-in support for the API endpoints because the Onramp API is in public preview. As a result, our examples use curl for backend interactions.

Create a crypto onramp session
サーバー側

On the server, expose a new API endpoint (for example, myserver.com/mint-onramp-session) that makes a call to the Stripe POST /v1/crypto/onramp_sessions endpoint. This mints an onramp session with Stripe you can use with new or returning customers. You must mint one session per customer.

Create a crypto onramp session by running the following curl command in your terminal:

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

次のようなレスポンスを受信します。

{
  "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
    }
  }
}

エラー

This endpoint returns error codes if Stripe can’t create onramp sessions. To learn why this might happen, see Handle customer supportability and fraud. We recommend that you render the onramp component conditional when a customer gets an HTTP status 200 during session creation, providing a fallback UI that can deal with session creation errors.

For the full parameter list you can pass when creating a session, see the Onramp API.

州

Each onramp session progresses through the following states:

initialized: The app has newly minted the onramp session on the server-side, but the customer hasn’t used it yet. Sessions are in this state until the customer onboards and is ready to pay.
rejected: Stripe rejected the customer for some reason (KYC failure, sanctions screening issues, fraud checks).
requires_payment: The customer has completed onboarding or sign-in and gets to the payment page. If they attempt payment and fail, they stay in this state.
fulfillment_processing: 顧客が正常に決済を完了しました。顧客が購入した暗号資産はまだ送信されていません。
fulfillment_complete: 顧客が暗号資産に対する決済を正常に行い、Stripe は暗号資産の送信を確認しました。

オプションCustomize the appearance of the onramp

You can customize the appearance of the onramp.

ブランディングを更新

Use the branding settings to upload your logo and brand colors which automatically apply to onramp sessions created with your platform API key.

Enable dark mode

To enable dark mode, include an appearance structure in the session creation call:

const onrampSession = stripeOnramp.createSession({
  clientSecret: clientSecret,
  appearance: {
    theme: 'dark'
  },
});

appearance を指定しなかった場合、オンランプはデフォルトでライトテーマになります。テーマはオンランプのレンダリング後に以下を呼び出すことでも変更できます。

onrampSession.setAppearance({
  theme: newTheme
});

オプションPre-populate paramaters

You can pre-populate some of the parameters of the onramp session.

取引パラメーターに事前入力する

For example, a Dapp or wallet can already store a customer’s wallet_addresses. You can achieve this during session creation:

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \
  -d "source_currency"="usd" \
  -d "destination_currency"="eth" \
  -d "destination_network"="ethereum" \
  -d "destination_amount"="0.1234"

You receive a response such as:

{
  "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
    }
  }
}

次のパラメーターに事前入力できます。

wallet_addresses: 暗号資産の送信先とする推奨ウォレットアドレス (ウォレットの関連付け画面でのデフォルトの選択項目)
lock_wallet_address: 推奨ウォレットアドレスをロックするかどうか
source_currency: 取引の法定通貨 (現時点では、usd、eur のみ)
source_amount: 暗号資産の購入に使用する法定通貨の金額 (目的金額と相互排他的)
destination_network: このオンランプのデフォルト暗号資産ネットワーク (例: ethereum)
destination_currency: このオンランプセッションのデフォルト暗号資産 (例: eth)
destination_amount: 購入する暗号資産の金額 (ソースの金額とは相互排他的)
destination_currencies: サポート対象とする暗号資産の配列 (例: [eth, usdc])
destination_networks: 限定先にする暗号資産ネットワークの配列 (例: [ethereum, polygon])。

For more details on the specific requirements and how they impact customers in the onramp UI, see Onramp API reference.

顧客情報を事前入力する

To help decrease customer friction and increase conversion, you might want to pre-populate some of the required KYC information for the customer if you’ve already collected it within your application.

Throughout the flow, customers must provide their:

メール
お名前 (名)
姓
生年月日
SSN
自宅住所 (国、住所 (1 行目)、住所 (2 行目)、市区町村、都道府県/州、郵便番号)

The Onramp API provides the ability to pre-populate all of those fields except for SSN. To pre-populate this information, you can provide it using the customer_information parameter in the OnrampSession creation API.

リクエスト例:

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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"

レスポンス例を以下に示します。

{
  "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
  }
}

次のパラメーターに事前入力できます。

customer_information.email—Freeform string for the customer’s email
customer_information.first_name—Freeform string for the customer’s first name
customer_information.last_name—Freeform string for the customer’s last name
customer_information.dob.year—Integer for the customer’s birth year
customer_information.dob.month—Integer for the customer’s birth month
customer_information.dob.day—Integer for the customer’s birth day
customer_information.address.country—String of the two letter country code for the customer’s country of residence
customer_information.address.line1—Freeform string for the customer’s address line one
customer_information.address.line2—Freeform string for the customer’s address line two
customer_information.address.city—Freeform string for the customer’s city
customer_information.address.state: アメリカの州の 2 文字の州コード (完全な州名も使用できます) を表す文字列 (例: “CA” または “California”)
customer_information.address.postal_code—Freeform string for the customer’s postal code

All of the fields are optional and you can provide any subset of them for pre-population. However, if you provide date of birth, you must also provide all three values for the following fields: year, month, and day.

オンランプ UI をレンダリングする
クライアント側

StripeJS と OnrampJS の両方のバンドルをインポートします。

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/clover/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>

前のステップのサーバー側の呼び出しから client_secret を使用し、オンランプセッションの開始とマウントを行います。

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");
}

スクリプトを実行すると、オンランプに以下のダイアログが表示されます。

Stripe による法定通貨から暗号資産へのオンランプがサードパーティーアプリケーションに埋め込まれる

サードパーティーアプリケーションに埋め込まれた、Stripe による法定通貨から暗号資産へのオンランプ

サンドボックスの値

Warning

サンドボックスの取引金額は、事前に決定された限度額によって上書きされます。

次の値を使用して、サンドボックスでオンランプ取引を完了します。

OTP 画面で、確認コードに 000000 を使用します。
個人情報画面で、SSN には 000000000 を使用して、住所 (1 行目) には address_full_match を使用します。
支払いの詳細画面で、テスト用クレジットカード番号 4242424242424242 を使用します。

実装の使用状況を表示

オンランプを起動した後、Stripe ダッシュボードでカスタマイズされた使用量レポートを表示できます。また、アカウント登録ページに戻って、オンランプのホストを計画しているドメインを更新し、アカウント登録タスクのステータスを確認することもできます。

オプションモバイル用にオンランプを設定する

Integrate Stripe’s crypto onramp UI into mobile web views and browsers by minting a session, hosting the onramp UI, completing the purchase, and redirecting customers back to the mobile app.

セッションを発行する

Similar to other integrations, you need to implement a server endpoint to create a new onramp session for every customer visit. The endpoint returns a client_secret that can load the onramp UI or display an error if the onramp is unavailable.

オンランプ UI をホストする

フロントエンドルートを作成する (たとえば、www.my-web3-wallet.com/onramp/<client_secret>) ことで、オンランプ UI をホストします。/onramp/<client_secret> は 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>

ここで、onramp.js が URL から client_secret を使用して、オンランプ UI をマウントします。

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);
  }
}

Configure universal links to deep link /onramp_success back to your mobile app. Consider providing a fallback or onramp_success page to prompt customers to manually switch back to your app.

購入を完了する

As with a standard integration, the front-end client controls the entire onramp UI. The UI adapts to fit the screen size. As the session state changes and we gather more transaction_details, the CryptoOnrampSession object updates accordingly. We generate webhooks and front-end events for every status transition. By using front-end event listeners, you can redirect customers back to your application flow when the OnrampSession completes.

モバイルアプリにリダイレクトする

Using a deep link or manual switch, customers can resume their flow in your mobile application. Your mobile application can use your back end to continue querying the CryptoOnrampSession state.

For example, if a customer is topping up their balance during initial setup, you can redirect them back to your application as soon as the session transitions to fulfillment_processing. You can allow customers to explore the rest of your application while polling the OnrampSession status in the background.

オプションコンバージョンの見積もりを設定する

The Onramp Quotes API lets you fetch estimated quotes for onramp conversions into various cryptocurrencies on different networks. You can specify a fixed source or destination amount and limit the quotes to a subset of destination currencies or networks. This API allows you to display quotes in your product UI before directing the customer to the onramp widget. If the quote expires before the customer visits the onramp widget, the customer might see a slightly different quote in the onramp widget.

コンバージョンの見積もりを取得する

GET /v1/crypto/onramp/quotes エンドポイントを使用して、コンバージョンの見積もりを取得します。次の表は、このエンドポイントで使用できるすべてのパラメーターをまとめたものです。

パラメーター	タイプ	デフォルト	詳細
`source_currency`	文字列 (オプション)	`usd`	ISO-4217 通貨コード。現時点では、`usd`、`eur` のみに対応しています。
`source_amount`	文字列 (オプション)	`100.00`	オンランプが必要な法定通貨の金額の文字列表現。`source_amount` が設定される場合、`destination_amount` は null にする必要があります (固定金額を設定できるのは取引の一方のみであるため、これらは相互排他的です)。
`destination_amount`	文字列 (オプション)	`null`	購入する `destination_currency` の金額の文字列表現。`destination_amount` を設定する場合、`source_amount` は null にする必要があります。このフィールドを指定する場合は、`destination_currencies` に単一値を、`destination_networks` にも単一値を指定する必要があります (これにより、Stripe で見積もり対象の暗号資産を認識できます)。
`destination_currencies`	配列<String> (オプション)	`null` `['usdc', 'ethereum']`	見積もり生成の対象となる暗号資産のリスト。`null` のままである場合は、`destination_networks` がサポートしているすべての `destination_currencies` の見積もりを取得します。通貨: `btc`、`eth`、`sol`、`matic`、`usdc`、`xlm`
`destination_networks`	配列<String> (オプション)	`null` `['polygon', 'bitcoin', 'solana', 'ethereum']`	見積もりを生成する暗号資産ネットワークのリスト。`null` のままである場合は、すべてのネットワークの `destination_currencies` の見積もりを取得します。ネットワーク: `bitcoin`、`ethereum`、`solana`、`polygon` 、`stellar`

見積もりリクエストの例

デフォルトのソースの金額が 100 USD の宛先通貨とネットワークのペアをすべて取得するには、次のコマンドを実行します。

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
:

次のようなレスポンスを受信します。

{
  "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"
}

ソースの金額が 200 USD の宛先通貨とネットワークのペアをすべて取得するには、次のコマンドを実行します。

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
    -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
    -d "source_amount"="200"

次のようなレスポンスを受信します。

{
  "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"
}

イーサリアムとソラナのネットワークで ETH と SOL の見積もりを取得するには、次のコマンドを実行します (イーサリアムでは ETH に、ソラナのネットワークでは SOL が返されます)。destination_currencies と destination_networks を指定すると、クロス積の有効な通貨とネットワークのペアごとに見積もりが返されます。destination_currencies のデフォルト値はすべての通貨で、destination_networks のデフォルト値はすべてのネットワークです。

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
      -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
      -d "source_amount"="200" \
      -d "destination_currencies[]"="eth" \
      -d "destination_currencies[]"="sol" \
      -d "destination_networks[]"="ethereum" \
      -d "destination_networks[]"="solana"

次のようなレスポンスを受信します。

{
  "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"
}

イーサリアムとソラナで USDC の見積もりを取得するには、次のコマンドを実行します。

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "source_amount"="200" \
  -d "destination_currencies[]"="usdc" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_networks[]"="solana"

次のようなレスポンスを受信します。

{
  "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"
}

destination_amount が指定された単一の支払い先の通貨とネットワークのペア (イーサリアムの ETH) の見積もりを取得するには、次のコマンドを実行します。

Command Line
curl -G https://api.stripe.com/v1/crypto/onramp/quotes \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "destination_amount"="0.42" \
  -d "destination_currencies[]"="eth" \
  -d "destination_networks[]"="ethereum"

次のようなレスポンスを受信します。

{
  "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"
}

オプションWebhook イベントをリッスンする

We send a crypto.onramp_session_updated webhook every time the status of an onramp session changes post creation. We don’t send an event when a new session is created. Configure webhooks in the Dashboard.

The webhook uses the CryptoOnrampSession resource:

{
  "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
        }
      }
    }
  }
}

Front end events

You can subscribe to the following front end events:

// 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},
}

As shown above, you can subscribe or unsubscribe to events using the standard addEventListener/removeEventListener functions over OnrampSession. You can use '*' to match all events.

オプションHandle customer supportability and fraud

Stripe enforces limitations on the Embedded onramp for customer supportability and in the event of fraud attacks.

Check customer supportablity

Pass customer_ip_address during session creation so we can preemptively check the aforementioned limitation.

The endpoint returns HTTP 400 with code=crypto_onramp_unsupportable_customer if the customer is in a geography we can’t support (based on customer_ip_address) You might want to hide the onramp option from customers in this case. Otherwise, our onramp UI renders in a disabled state.

Here’s a sample request illustrating this behavior:

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer_ip_address"="8.8.8.8" \

Sample response (400):

{
  "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."
  }
}

不正利用攻撃に対処する

Stripe serves as the merchant of record and takes on the liability for disputes and fraud. We might decide to temporarily restrict creation of onramp sessions if we detect a high risk situation (for example, if we see active attacks and exploits).

If we need to shut off the API because of an unbounded fraud attack, we return the following when anyone attempts to create a new session:

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \

次のようなレスポンスを受信します。

{
  "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
  }
}

Additional validation and errors

条件	HTTP ステータス	エラーコード
インシデントのため、新しいセッションを発行できません	400	`crypto_onramp_disabled`
`customer_ip_address` パラメーターに基づき、Stripe では指定された顧客をサポートできません。	400	`crypto_onramp_unsupported_country` または `crypto_onramp_unsupportable_customer`
`/v1/crypto/onramp_session` エンドポイントに渡された `customer_ip_address` の形式が正しくありません	400	`customer_ip_address`
`source_amount` と `destination_amount` は相互排他的ですが、プラットフォームでは両方が設定されています。	400	`crypto_onramp_invalid_source_destination_pair`
`destination_currency` と `destination_network` の一方が設定されていますが、もう一方が設定されていません	400	`crypto_onramp_incomplete_destination_currency_and_network_pair`
`destination_currency` と `destination_network` の組み合わせが無効です	400	`crypto_onramp_invalid_destination_currency_and_network_pair`
`source_amount` が設定されていますが、`source_currency` が設定されていません	400	`crypto_onramp_missing_source_currency`
`source_amount` が正の数ではありません	400	`crypto_onramp_invalid_source_amount`
`destination_amount` が設定されていますが、`destination_currency` が設定されていません	400	`crypto_onramp_missing_destination_currency`
`destination_amount` が正の数ではありません	400	`crypto_onramp_invalid_destination_amount`
`destination_currencies` と `destination_networks` の組み合わせに、サポートされている通貨がありません	400	`crypto_onramp_invalid_destination_currencies_and_networks`
`destination_currency` が `destination_currencies` に含まれていません	400	`crypto_onramp_conflicting_destination_currency`
`destination_network` が `destination_networks` に含まれていません	400	`crypto_onramp_conflicting_destination_network`
`wallet_addresses` のウォレットアドレスの 1 つ以上が、`destination_networks` に含まれていないネットワークに関連付けられています	400	`crypto_onramp_wallet_addresses_not_all_networks_supported`
`wallet_addresses` にウォレットアドレスが指定されていませんが、`lock_wallet_address` が true に設定されていました	400	`crypto_onramp_no_wallet_address_to_lock`
ビジネスの `business_name` フィールドまたは `business_url` フィールドが設定されていません。これらのフィールドは、ダッシュボードの `Public business name` と `Business website` で入力されています。	400	`crypto_onramp_merchant_not_properly_setup`

オプションUse session persistence

You can use session persistence to help you provide notifications and keep customers engaged with the onramp after fulfilling their purchase.

セッションの持続機能のメリット

You might want to persist an onramp session across customer visits in some instances. For example, when a customer’s onramp session is disrupted or dropped, you could prompt them and provide ways to resume the onramp session later. Or if a customer refreshes the page after completing the payment, you can retain the ability to notify them when a previous onramp purchase was fulfilled.

For this reason, the OnrampSession object is stateful and stored as a server side resource. By initializing the onramp UI using a previously used OnrampSession client secret, customers return to where they left off.

セッションの持続機能の設定

A client secret is a unique identifier for the onramp session that stores the lifecycle of a session without leaking sensitive payment information. However, it exposes private information such as wallet addresses. Don’t log it, embed it in URLs, or expose it to anyone other than the customer. Make sure that you have TLS on any page that includes the client secret.

If you have a Web2-like account structure, you could link OnrampSession to your customer object and fetch it upon authentication. For an account-less Web3 application, it would add customer friction to require the use of message signing for authentication. Privacy-preserving local storage yields an acceptable customer experience.

オプションConfigure the onramp by use case

You can configure the onramp session parameters based on use case:

ウォレット
Dapp または NFT の決済
Decentralized Exchange (DEX) integration

To make onramp appear to be part of your product UI, frame the onramp as a native component of your application.

ウォレット

Wallet customers have two main onramp entry points: wallet funding and transaction top-ups.

ウォレットへの資金追加

You can proactively prompt customers to fund their wallet after they create a new wallet or when their funds are critically low.

これらのケースでは、以下のパラメーターを指定することを検討してください。

wallet_addresses: すでに使用しているウォレットアドレスを使用します。
destination_networks: Set to the default or selected network to reduce customer confusion.
destination_currencies: You can leave this blank, but you can also restrict it to the native gas token or any desired cryptocurrencies. For example, if you offer a DeFi service in USDC, consider that the customer likely needs both USDC and the gas token.
destination_network: これを空白のままにすると、サポートされているネットワークの最初の値を継承します。
destination_currency: これを空白にすると、サポート対象の暗号資産の最初の値を継承します。

以下のコード例は、これらのパラメーターのいくつかを使用したオンランプセッションの作成方法を示しています。

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer_ip_address"="8.8.8.8" \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \
  -d "wallet_addresses[solana]"="bufoH37MTiMTNAfBS4VEZ94dCEwMsmeSijD2vZRShuV" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_networks[]"="solana"

取引のトップアップ

When a Dapp or customer proposes a transaction, you might detect that the transaction fails because of insufficient funds. In this case, you can calculate the delta required for the transaction to complete. However, it’s often difficult to detect the requested amount or cryptocurrency for ERC or SPL tokens.

これらのケースでは、以下を指定することを検討してください。

wallet_addresses: 使用しているウォレットアドレスを使用します。
destination_networks: 選択したネットワークに設定します。
destination_currencies: 可能な場合は不足している通貨に限定します。
destination_network: 選択したネットワークに設定します (金額を設定する場合は必須値)。
destination_currency: ターゲット通貨に設定します (金額を設定する場合は必須値)。
destination_amount: 残高の差異に設定し、できればガス (手数料) 用に十分な余地を残しておきます。

以下のコード例は、これらのパラメーターのいくつかを使用したオンランプセッションの作成方法を示しています。

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer_ip_address"="8.8.8.8" \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_currencies[]"="usdc" \
  -d "destination_network"="ethereum" \
  -d "destination_currency"="usdc" \
  -d "destination_amount"="10"

Dapp または NFT の決済

You can use the onramp in checkout when you know the destination amount. For example, a Dapp might sell memberships for a fixed price, or a customer might want to buy a specific NFT from a marketplace.

これらのケースでは、以下を指定することを検討してください。

wallet_addresses: 接続されているウォレットアドレスを使用します。
destination_networks: 接続されているネットワークを使用します。
destination_currencies: 取引通貨 (商品の見積もりに使用される通貨での価格) を使用します
destination_network: 上記の選択したネットワークに設定します (金額を設定する場合は必須値)。
destination_currency: 上記のターゲット通貨に設定します (金額を設定する場合は必須値)
destination_amount: Set it to either the balance difference or to cover the entire purchase amount. Some customers adopt both, using on-chain analytics with an almost even split. A customer might choose the full amount to simplify their tax cost basis or to avoid spending accumulated assets. In both cases, leave room for gas.

以下のコード例は、これらのパラメーターのいくつかを使用したオンランプセッションの作成方法を示しています。

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer_ip_address"="8.8.8.8" \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_currencies[]"="eth" \
  -d "destination_network"="ethereum" \
  -d "destination_currency"="eth" \
  -d "destination_amount"="0.2343"

DEX

A DEX offers a unique opportunity to let customers buy any cryptocurrency with fiat. While a DEX can prompt customers to top up crypto when exchanging arbitrary crypto pairs using an existing interface, it’s better to have a dedicated customer flow that focuses on fiat to crypto only.

As the onramp lets you control your brand and UI, a DEX can build an onramp widget that uses Stripe’s ability to process fiat into select cryptocurrencies. The DEX can then complete the final exchange to arbitrary currencies. A DEX can also build an onramp widget for a specific token. For example, a DAO might endorse a specific liquidity pool and use a DEX to distribute their tokens and onboard new customers with fiat.

これらのケースでは、以下を指定することを検討してください。

wallet_addresses: すでに使用しているウォレットアドレスを使用します。
destination_networks: 選択したネットワークに設定します。
destination_currencies: 選択した暗号資産に限定します。
destination_network: 選択したネットワークに設定します (金額を設定する場合は必須値)。
destination_currency: ターゲット通貨に設定します (金額を設定する場合は必須値)
destination_amount: Set only if you can collect the customer’s intent ahead of time—leave blank for Stripe to suggest smart default values.

以下のコード例は、これらのパラメーターのいくつかを使用したオンランプセッションの作成方法を示しています。

Command Line
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer_ip_address"="8.8.8.8" \
  -d "wallet_addresses[ethereum]"="0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2" \
  -d "destination_networks[]"="ethereum" \
  -d "destination_currencies[]"="eth" \
  -d "destination_network"="ethereum" \
  -d "destination_currency"="eth"

Note

組み込みオンランプの導入公開プレビュー

このガイドを使用して、埋め込み可能なオンランプを全面的にカスタマイズできます。

はじめに

SDK およびクライアントライブラリをインストールするクライアント側サーバー側

クライアント側

JS SDK

Alternative SDK installation

サーバー側

Create a crypto onramp sessionサーバー側

エラー

州

オプションCustomize the appearance of the onramp

ブランディングを更新

Enable dark mode

オプションPre-populate paramaters

取引パラメーターに事前入力する

顧客情報を事前入力する

オンランプ UI をレンダリングするクライアント側

サンドボックスの値

Warning

実装の使用状況を表示

オプションモバイル用にオンランプを設定する

セッションを発行する

オンランプ UI をホストする

購入を完了する

モバイルアプリにリダイレクトする

オプションコンバージョンの見積もりを設定する

コンバージョンの見積もりを取得する

見積もりリクエストの例

オプションWebhook イベントをリッスンする

Front end events

オプションHandle customer supportability and fraud

Check customer supportablity

不正利用攻撃に対処する

Additional validation and errors

オプションUse session persistence

セッションの持続機能のメリット

セッションの持続機能の設定

オプションConfigure the onramp by use case

ウォレット

ウォレットへの資金追加

取引のトップアップ

Dapp または NFT の決済

DEX

SDK およびクライアントライブラリをインストールする
クライアント側
サーバー側

Create a crypto onramp session
サーバー側

オンランプ UI をレンダリングする
クライアント側