オンランプ API リファレンス公開プレビュー

埋め込み可能なオンランプを構築する際、オンランプの API リファレンスを利用してください。

ページをコピー

オンランプの実装を構築する際には以下の開発者フローをご覧ください。

オンランプをアプリケーションに実装する

本番環境を使用する前に、Stripe は、オンランプのお申し込みを承認する必要があります。

始める

アプリケーションをオンランプに実装するには、以下の手順に従います。

Stripe にアカウント登録した後、ダッシュボードを使用して、secret と公開可能 API キーを取得します。
CryptoOnrampSession をサーバー側で生成します。
サーバーで、新しい API エンドポイント (たとえば、myserver.com/mint-onramp-session) を公開します。このエンドポイントは、Stripe POST /v1/crypto/onramp_sessions エンドポイントへのコールを行います。これにより、新規ユーザーやリピートユーザーで使用できるオンランプセッションが Stripe で「発行」されます。ユーザーごとにセッションを 1 つ発行する必要があります。

次のコマンドを実行します。

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

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

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

このエンドポイントは、Stripe がオンランプセッションを作成できない場合にエラーコードを返します。この状況が発生する理由については、下記のサポート対応状況のセクションでご確認ください。セッションの作成時にユーザーが HTTP ステータス 200 を受け取った場合にオンランプコンポーネントをレンダリングし、セッション作成エラーを処理できるフォールバック UI を用意することをお勧めします。

フロントエンドでセッション client_secret を使用する

オンランプコンポーネントを初期化するには、以下が必要です。

公開可能 API キー。
POST /v1/crypto/onramp_sessions へのリクエストで取得した client_secret。

下記のコードは iframe を #onramp-elementノードにマウントします。このノードは、オンランプのすべてをホストしています。イベントリスナーを使用して、アプリケーションの機能を向上させることができます。たとえば、仮想通貨購入後に分散型アプリケーション (Dapp) で操作を再開できます。登録できるイベントについては、フロントエンドイベントをご覧ください。

index.html
<!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("pk_test_TYooMQauvdEDq54NiTphI7jx"
);
      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>

CryptoOnramp 要素がレンダリングされ、引き継がれる

上記の CryptoOnramp HTML 要素がレンダリングされると、フロントエンドクライアントがインターフェイスを制御します。セッションの状態が変化し、transaction_details に関する詳細を収集すると、CryptoOnrampSession オブジェクトがそれに従って更新されます。ステータスの移行が発生するたびに、Webhook およびフロントエンドのイベントが生成されます。フロントエンドイベントリスナーを使用して、オンランプセッションの完了後にユーザーをアプリケーションユーザーフローにリダイレクトして戻すことができます。

(オプション) オンランプのデザインを変更する

ダークモードを有効にするには、上記のセッション作成コールに appearance 構造を含めます。

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

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

onrampSession.setAppearance({
  theme: newTheme
});

ブランディング設定を使用して、ロゴおよびブランドカラーをアップロードできます。いずれも、プラットフォーム API キーを使用して作成されたオンランプセッションに自動的に適用されます。

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

シームレスなオンランプユーザーフローを提供するために、オンランプセッションの一部のパラメーターに事前入力できます。たとえば、Dapp やウォレットではユーザーの wallet_addresses がすでにわかっています。これを行うには、セッション作成時に以下のようにします。

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"

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

{
  "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])

具体的な要件およびオンランプ UI におけるユーザーへの影響について、詳細は API リファレンスをご覧ください。

顧客情報を事前入力する

必要な顧客確認情報の一部をすでにアプリケーション内で収集している場合は、ユーザーの代わりに事前入力することでオンランプフローにおけるユーザーの負担を減らし、コンバージョン率を向上させることができます。

フロー全体を通して、ユーザーは少なくとも以下を指定する必要があります。

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

Onramp API は、SSN 以外のすべてのフィールドに事前入力できる機能を提供します。この情報を事前入力するには、OnrampSession creation API で customer_information パラメーターを使用して指定します。

リクエスト例:

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: ユーザーのメールアドレスを表す自由形式の文字列
customer_information.first_name: ユーザーの名を表す自由形式の文字列
customer_information.last_name: ユーザーの姓を表す自由形式の文字列
customer_information.dob.year: ユーザーの生年月日の年を表す整数
customer_information.dob.month: ユーザーの生年月日の月を表す整数
customer_information.dob.day: ユーザーの生年月日の日付を表す整数
customer_information.address.country: ユーザーの居住国の国コードを表す 2 文字の文字列
customer_information.address.line1: ユーザーの住所 (1 行目) を表す自由形式の文字列
customer_information.address.line2: ユーザーの住所 (2 行目) を表す自由形式の文字列
customer_information.address.city: ユーザーの市区町村を表す自由形式の文字列
customer_information.address.state: アメリカの州の 2 文字の州コード (完全な州名も使用できます) を表す文字列 (例: “CA” または “California”)
customer_information.address.postal_code: ユーザーの郵便番号を表す自由形式の文字列

すべてのフィールドはオプションで、事前入力の対象としてその一部を指定できます。ただし、生年月日を指定する場合は、year、month、day のすべてを指定する必要があります (生年月日フィールドの 1 つまたは 2 つのみを指定することはできません)。

ユーザーサポート対応範囲と不正利用に対処する

Stripe では対象とするユーザーの範囲に対して、また不正利用攻撃が発生した場合にオンランプ製品に制限を適用します。

サポート対応状況を確認する

地域的な考慮事項
アメリカ
EU

オンランプは、アメリカ (ハワイを除く) と EU 加盟国でのみ利用できます。

セッション作成時に customer_ip_address を渡して、前述の制限を Stripe で前もって確認できるようにします。顧客が弊社のサポート対象外の地域に在住している場合 (customer_ip_address に基づく) 、エンドポイントから HTTP 400 と code=crypto_onramp_unsupportable_customer が返されます。

この場合は、オンランプオプションがユーザーに表示されないようにする必要があります。そうしなかった場合は、Stripe のオンランプ UI が disabled 状態でレンダリングされます。

この動作を示すリクエストとレスポンス (400) のサンプルを次に示します。

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

{
  "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 は、取引に関する金銭的責任を負い、すべての不審請求の申請と不正利用に対して責任を負います。Stripe はリスク管理の深い専門知識を有していますが、ハイリスクの状況が検出された場合 (たとえば、活発な攻撃や悪用が見つかった場合)、オンランプセッションの作成を一時的に制限することがあります。

際限のない不正利用攻撃が原因で API を停止する必要がある場合は、新しいセッションの作成が試行されると Stripe から以下を返します。

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

API リファレンス

CryptoOnrampSession リソース

CryptoOnrampSession リソースは次のようになります。

{
  "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 のステートマシン

status フィールドは、次の状態でセッションのステートマシンを表します。

initialized: アプリケーションがサーバー側でオンランプセッションを新規に発行しましたが、まだ顧客は使用していません。ユーザーがアカウント登録を行って決済の準備ができるまで、セッションはこの状態になります。
rejected: いずれかの理由により (顧客確認の失敗、制裁遵守のためのスクリーニングの問題、不正利用チェック)、Stripe が顧客を拒否しました。
requires_payment: ユーザーがアカウント登録を完了するか、サインインして決済ページに進みました。決済を試行して失敗した場合は、このステータスのままになります。
fulfillment_processing: 顧客が正常に決済を完了しました。顧客が購入した仮想通貨はまだ送信されていません。
fulfillment_complete: 顧客が仮想通貨に対する決済を正常に行い、Stripe は仮想通貨の送信を確認しました。

CryptoOnrampSession の操作

すべてのエンドポイントで、API キーを使用した認証が要求されます。リクエスト例では認証ヘッダーが省略されています。

アプリケーションでは CryptoOnrampSession で次の操作を実行できます。

セッションを作成する
既存のセッションを取得する

セッションを作成する

エンドポイント: POST /v1/crypto/onramp_sessions

パラメーター名	型 (オプションか) デフォルト: ?	詳細
wallet_addresses	文字列 (オプション) デフォルト: null	この取引で使用する、最終顧客の (各ネットワークの) 仮想通貨ウォレットアドレス。 null のままにした場合はユーザーがオンランプ UI でウォレットを入力します。設定されている場合、プラットフォームでは `destination_networks` または `destination_network` のいずれかを設定する必要があります。Stripe ではアドレスの検証を実行します。ただしこの場合も、ユーザーはオンランプ UI で別のウォレットを選択できます。デスティネーションタグまたはメモを使用するアセットの場合、`destination_tags` マップを `wallet_addresses` にネストして、ユーザーの指定のデスティネーションタグにアセットをマッピングできます。
source_currency	文字列 (オプション) デフォルト: null	オンランプセッションのデフォルトのソース法定通貨。 null のままにしたときは、ユーザーのロケールに基づいてデフォルトの通貨が選択されます。設定されている場合は、オンランプでサポートされている法定通貨のいずれかでなければなりません。ただし、この場合もユーザーはオンランプ UI で別の通貨を選択できます。
source_amount	文字列 (オプション) デフォルト: null	仮想通貨に交換する法定通貨のデフォルト金額 (小数)。 null のままにした場合に `destination_amount` が設定されていると、デフォルト値が計算されます。これが設定されていると、`source_amount` の設定が `destination_amount` の設定と相互排他的になります (どちらか一方のみがサポートされます)。小数のセントはサポートしていません。補助通貨単位の小数が渡された場合、エラーが生成されます。ユーザーはオンランプ UI で値を更新できます。
destination_networks	配列<String> (オプション) デフォルト: null	ユーザーが選択できる宛先仮想通貨ネットワークのリスト。 null のままにすると、オンランプ UI でサポートされているすべての仮想通貨ネットワークが表示されます。設定されている場合、空でない配列で、配列内の各値が有効な仮想通貨ネットワークでなければなりません。使用可能値は、`{solana, ethereum, bitcoin, polygon}` です。これを使用して単一値の配列を渡すことで、ユーザーを特定のネットワークにロックできます。ユーザーはこのパラメーターを上書きできません。
destination_currencies	配列<String> (オプション) デフォルト: null	ユーザーが選択できる目的仮想通貨のリスト。 null のままにすると、`destination_networks` が設定されている場合はオンランプ UI でサポートされているすべての仮想通貨が表示されます。設定されている場合、空でない配列で、配列内のすべての値が有効な仮想通貨でなければなりません。有効な値は、`{eth, matic, sol, usdc, btc}` です。これを使用して単一値の配列を渡すことで、ユーザーを特定の仮想通貨にロックできます。ユーザーはこのパラメーターを上書きできません。
destination_network	文字列 (オプション) デフォルト: null	デフォルトの宛先仮想通貨ネットワーク。 null のままにすると、`destination_networks` の最初の値が選択されます。設定されているときに `destination_networks` も設定されている場合は、`destination_network` の値がその配列内に存在しなければなりません。`destination_network` をロックするには、その値を `destination_networks` の単一値として指定します。サポートされている宛先ネットワークは `{solana, bitcoin, ethereum, polygon}` です。ユーザーは、`destination_networks` が設定されている場合はその設定に従い、オンランプ UI で別のネットワークを選択できます。
destination_currency	文字列 (オプション) デフォルト: null	デフォルトの目的仮想通貨。 null のままにすると、`destination_currencies` の最初の値が選択されます。設定されているときに `destination_currencies` も設定されている場合は、`destination_currency` の値がその配列内に存在しなければなりません。`destination_currency` をロックするには、その値を `destination_currencies` の単一値として指定します。サポートされている目的通貨は `{eth, matic, sol, usdc, btc}` です。ユーザーは、`destination_currencies` が設定されている場合はその設定に従い、オンランプ UI で別の仮想通貨を選択できます。
destination_amount	文字列 (オプション) デフォルト: null	交換後の仮想通貨のデフォルトの金額。 null のままにした場合に `source_amount`、`destination_currency`、および `destination_network` が設定されていると、デフォルト値が計算されます。設定されている場合、`destination_currency` と `destination_network` もともに設定する必要があります。仮想通貨はすべて、その最大精度までサポートされています (たとえば、`eth` では小数第 18 位まで)。Stripe では検証を実行し、金額が換算通貨に基づいてサポートされている精度を超えている場合は、エラーを生成します。`source_amount` の設定は `destination_amount` の設定と相互排他的です (どちらか一方のみがサポートされます)。ユーザーはオンランプ UI で金額を更新できます。
customer_ip_address	文字列 (オプション) デフォルト: null	プラットフォームがオンランプする顧客の IP アドレス。ユーザーの IP が Stripe でサポートできない地域内のものである場合、`HTTP 400` と該当するエラーコードが返されます。Stripe では IPv4 アドレスと IPv6 アドレスをサポートしています。地理的なサポート対応状況は後からオンランプフローでもう一度確認されます。これにより、オンランプフローでは、対象外のユーザーにオンランプオプションが表示されないようにしてユーザー体験を向上させることができます。

リクエストとレスポンスのサンプル:

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_currencies[]"="eth" \
  -d "destination_networks[]"="ethereum"

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

セッションを取得する

エンドポイント: GET /v1/crypto/onramp_sessions/:id

パラメーター名	型 (オプションか) デフォルト: ?	詳細
この操作ではサポートされているパラメーターはありません。

以下にリクエストの例を示します。

Command Line
curl -X GET https://api.stripe.com/v1/crypto/onramp_sessions/cos_0MYvv9589O8KAxCGPm84FhVR \
  -usk_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
    }
  }
}

検証とエラー

条件	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`

複数のセッションを取得する

エンドポイント: GET /v1/crypto/onramp_sessions

リストエンドポイントを使用して、複数のオンランプセッションを同時に取得します。

Webhook

オンランプセッションの作成後はステータスが変化するたびに crypto.onramp_session_updated Webhook を送信します。新規セッションの作成時には Webhook は送信しません。ダッシュボードで Webhook を設定できます。

Webhook で使用されるリソースは上の 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
        }
      }
    }
  }
}

フロントエンドイベント

以下は、登録できるフロントエンドイベントの一覧です。

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

上記のように、OnrampSession で標準 addEventListener/removeEventListener 関数を使用して、イベントを登録したり登録解除したりできます。'*' を使用すると、すべてのイベントに一致させることができます。

セッションの持続機能

セッションの持続機能を使用すると、通知を提供したり、購入の完了後にユーザーをオンランプに関与させつづけることができます。

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

ユーザーによる複数回のアクセスにわたってオンランプセッションを持続させることが必要になる場合があります。たとえば、ユーザーのオンランプセッションが中断または終了された場合に、それをユーザーに知らせたり、後からオンランプセッションを再開する手段を用意したりすることができます。あるいは、ユーザーが決済を完了した後にページを更新した場合に、前のオンランプでの購入が完了していることを通知することもできます。このため、OnrampSession オブジェクトはステートフルであり、サーバー側のリソースとして保存されます。以前に使用した OnrampSession client secret を使用してオンランプ UI を初期化することで、ユーザーは前回終了したところに戻ります。

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

client secret はオンランプセッションの一意の識別子であり、機密の決済情報を漏えいさせることなくセッションのライフサイクルを格納します。ただし、ウォレットアドレスなどのプライベート情報は公開します。そのため、ログに記録したり、URL に埋め込んだり、顧客以外の第三者に公開したりしないでください。client secret が含まれるページのすべてで必ず TLS を使用してください。Web2 のようなアカウント構造を使用している場合は、OnrampSession をユーザーオブジェクトにリンクし、認証時に取得できます。アカウントのない Web3 アプリケーションでは、認証にメッセージ署名を使用しなければならないようにすると、ユーザーの負担が増します。プライバシーが保たれるローカルストレージを使用することで、ユーザー体験を受け入れられやすいものにすることができます。

オンランプ API リファレンス公開プレビュー

埋め込み可能なオンランプを構築する際、オンランプの API リファレンスを利用してください。

オンランプをアプリケーションに実装する

始める

フロントエンドでセッション client_secret を使用する

CryptoOnramp 要素がレンダリングされ、引き継がれる

(オプション) オンランプのデザインを変更する

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

顧客情報を事前入力する

ユーザーサポート対応範囲と不正利用に対処する

サポート対応状況を確認する

地域的な考慮事項アメリカEU

不正利用攻撃に対処する

API リファレンス

CryptoOnrampSession リソース

CryptoOnrampSession のステートマシン

CryptoOnrampSession の操作

セッションを作成する

セッションを取得する

検証とエラー

複数のセッションを取得する

Webhook

フロントエンドイベント

セッションの持続機能

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

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

地域的な考慮事項
アメリカ
EU