埋め込み可能なオンランプ導入の設定公開プレビュー

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

このガイドは、組み込み型オンランプクイックスタートの拡張版です。次のような機能の追加方法をご覧ください。

スクリプトタグまたはパッケージマネージャーを使用した SDK のインストール
仮想通貨へのオンランプ換算の推定見積もりの取得
モバイル Web ビューへのオンランプ UI の設定

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

クライアント側

以下のスクリプトを、script タグを使用して HTML の <head> 要素内に含めます。互換性と PCI 準拠のため、このスクリプトは常に Stripe のドメイン (https://js.stripe.com、https://crypto-js.stripe.com) から直接読み込んでください。このスクリプトをバンドルに含めたり、そのコピーを自分でホストしたりしないでください。その場合、警告なしに実装が壊れる可能性があります。

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>

オンランプ JS SDK をモジュールとして使用する

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

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

代替 SDK のインストール

または、スクリプトタグまたはパッケージマネージャーを使用して、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/basil/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');
```

サーバー側

オンランプ API は限定的なベータ版であるため、公式ライブラリには API エンドポイントのサポートが含まれていません。このため、サンプルではバックエンドとのやり取りに curl を使用しています。

仮想通貨オンランプセッションを生成する
サーバー側

端末で次の curl コマンドを実行して、仮想通貨オンランプセッションを生成します。

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

セッションの作成時に渡すことができる全パラメーターのリストについては、オンランプ API リファレンスをご覧ください。

オンランプ 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/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>

前のステップのサーバー側の呼び出しから 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 による法定通貨から仮想通貨へのオンランプ

サンドボックスの値

警告

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

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

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

実装の使用状況を表示

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

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

セッションを作成して、オンランプ UI をホストし、購入を完了して、ユーザーをモバイルアプリにリダイレクトすることで、Stripe の仮想通貨オンランプ UI をモバイルの Web ビューやブラウザに導入します。

セッションを発行する

他の導入と同様に、ユーザーがアクセスするたびに新規オンランプセッションを作成するサーバーエンドポイントを実装する必要があります。このエンドポイントは client_secret を返します。これにより、オンランプ UI を読み込み、オンランプが利用できない場合にエラーを表示することができます。

オンランプ 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);
  }
}

モバイルアプリに戻るディープリンク /onramp_success へのユニバーサルリンクを設定します。ユーザーに手動でアプリに切り替えるように求めるフォールバックまたは onramp_success ページを用意することを検討してください。

購入を完了する

標準的な導入と同様に、フロントエンドクライアントがオンランプ UI 全体を制御します。この UI は画面サイズに合うようにサイズが変更されます。セッションの状態が変化し、さらに transaction_details が収集されると、CryptoOnrampSession オブジェクトがそれに従って更新されます。ステータスが移行するたびに、Webhook とフロントエンドイベントが生成されます。フロントエンドイベントリスナーを使用することで、OnrampSession の完了時にユーザーをアプリケーションフローにリダイレクトできます。

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

ユーザーはディープリンクまたは手動切り替えを使用して、モバイルアプリケーションでフローを再開できます。モバイルアプリケーションではバックエンドを使用して、CryptoOnrampSession の状態のクエリを続行できます。

たとえば、ユーザーが初期設定時に残高にトップアップ (資金を追加) する場合、セッションが fulfillment_processing に移行した時点でユーザーをアプリケーションにリダイレクトできます。バックグラウンドで OnrampSession のステータスをポーリングしている間に、ユーザーがアプリケーションの残りの部分を確認できるようにすることができます。

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

Onramp Quotes API を使用すると、プラットフォームはさまざまなネットワークですべての仮想通貨へのオンランプ換算の見積もりを取得することができます。ソースまたは宛先の固定金額を指定して、宛先の通貨またはネットワークのサブセットに見積もりを制限することもできます。この API では、ユーザーをオンランプウィジェットに誘導する前に商品 UI で見積もりを表示することができます。ユーザーがオンランプウィジェットにアクセスする前に見積もりの有効期限が切れた場合は、オンランプウィジェットでユーザーに表示される見積もりが若干異なる可能性があります。

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

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

埋め込み可能なオンランプ導入の設定公開プレビュー

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

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

クライアント側

オンランプ JS SDK をモジュールとして使用する

代替 SDK のインストール

サーバー側

仮想通貨オンランプセッションを生成するサーバー側

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

サンドボックスの値

警告

実装の使用状況を表示

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

セッションを発行する

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

購入を完了する

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

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

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

見積もりリクエストの例

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

仮想通貨オンランプセッションを生成する
サーバー側

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