コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments
決済手段
支払いインターフェイス
決済シナリオ
店頭支払い
他の Stripe プロダクト

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

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

ページをコピー

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

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

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

始める

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

  1. Stripe にアカウント登録した後、ダッシュボードを使用して、secret と公開可能 API キーを取得します。

  2. CryptoOnrampSession をサーバー側で生成します。

  3. サーバーで、新しい API エンドポイント (たとえば、myserver.com/mint-onramp-session) を公開します。このエンドポイントは、Stripe POST /v1/crypto/onramp_sessions エンドポイントへのコールを行います。これにより、新規ユーザーやリピートユーザーで使用できるオンランプセッションが Stripe で「発行」されます。ユーザーごとにセッションを 1 つ発行する必要があります。

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

    Command Line
    curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
  -u 
    sk_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 \
  -u 
sk_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 \
  -u 
sk_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 \
  -u 
sk_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 \
  -u 
sk_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 フィールドは、次の状態でセッションのステートマシンを表します。

CryptoOnrampSession のステートマシン
  • 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 \
  -u 
sk_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 \
  -u 
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
    }
  }
}

検証とエラー

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

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc