# Shared Payment Token Shared Payment Token の使い方を解説します。 > 共有決済トークン (SPT) は、アメリカのエージェント、顧客、売り手が利用できます。 # 売り手 > This is a 売り手 for when agent-seller is seller. View the full page at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens?agent-seller=seller. 売り手は、エージェントから [Shared Payment Token (SPT)](https://docs.stripe.com/api/shared-payment/granted-token.md) を受け取ります。SPT は、顧客の決済手段を使用するための、範囲を限定した付与です。エージェントは、それぞれ使用上限と有効期限の制限付きで、[Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md)に SPT を付与します。 支払い方法登録とプロセス (See full diagram at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) ## Before you begin - [利用規約](https://stripe.com/legal/ssa-services-terms#stripe-agentic-commerce-seller-services-preview)に同意した上で、SPT を使用します。 - Stripe アカウントをまだお持ちでない場合には、[アカウントを作成](https://stripe.com/register)してください。 - Stripe ダッシュボードで [Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md)を作成してください。 ## SPT の受信をテストする テストヘルパーを使用して、エージェントによって付与された SPT の受け取りをシミュレーションできます。次のリクエストでは、テスト用の決済手段を使用してアカウントに SPT を付与し、通貨、最大金額、有効期限など、エージェントが指定できる制限をシミュレーションする方法を示します。 ```curl curl https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens \ -u "<>:" \ -d payment_method=pm_card_visa \ -d "usage_limits[currency]=usd" \ -d "usage_limits[max_amount]=1000" \ -d "usage_limits[expires_at]=1751587220" ``` ### 使用状況制限の設定 `usage_limits` パラメータを使用して最大金額と有効期限を指定します。エージェントは、取引の合計金額と一致するように最大金額を設定します。 ### 決済手段の指定 `payment_method` パラメータを使用して、顧客が購入に選択した決済手段を指定します。 ## 本番環境での実装をテストする 本番環境で実装をテストするには、[link-cli](https://link.com/agents) を使用して、個人の Link アカウントから SPT を発行できます。`link-cli` は、1 回限りの Shared Payment Token の認証情報をプロビジョニングできます。[link.com/agents](https://link.com/agents) の手順に従って `link-cli` スキルをインストールするか、使用するエージェントに MCP サーバーとして登録できます。 1. 個人用の Link アカウントにログインするか、アカウントがない場合は[登録](https://app.link.com)してください。 ```bash npx @stripe/link-cli auth login ``` 1. 使用する決済手段を選択してください。まだお持ちでない場合は、[決済手段を追加](https://app.link.com/wallet)できます。 ```bash npx @stripe/link-cli payment-methods list ``` 1. 事業者プロフィールにスコープが限定された 1 回限りの SPT を発行するために、支出リクエストを作成します。 ```bash npx @stripe/link-cli spend-request create \ --payment-method-id csmrpd_xxx \ --context "Machine payments with SPTs in live mode" \ --amount 100 \ --credential-type shared_payment_token \ --network-id profile_... \ --request-approval ``` ## Shared Payment Token の使用 付与された `SharedPaymentToken` を受け取ったら、`PaymentIntent` を作成して決済を完了します。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "payment_method_data[shared_payment_granted_token]=spt_123" \ -d confirm=true ``` SPT で `PaymentIntent` を確定すると、Stripe は `payment_method` を顧客の元の決済手段から複製された新しい `PaymentMethod` に設定します。返金やレポート作成などの後続のイベントは、`PaymentMethod` を直接指定したかのように動作します。 クレジットカードブランド、下 4 桁、使用状況の制限など、基になる決済手段に関する制限情報を含む、付与された `SharedPaymentToken` の詳細を取得できます。 ```curl curl https://api.stripe.com/v1/shared_payment/granted_tokens/spt_123 \ -u "<>:" ``` ``` { "id": "spt_123", "object": "shared_payment.granted_token", "created": 1751500820, "deactivated_at": null, "deactivated_reason": null, "usage_limits": { "currency": "usd", "expires_at": 1780309719, "max_amount": 1000 } ... } ``` ### Webhook イベントのリッスン Stripe は、以下の場合にお客様とエージェントにイベントを送信します。 - 承認された SPT を使用して決済を受け付けます。 - エージェントは許可された SPT を取り消します。取り消した SPT で決済を作成することはできません。 | イベント | 説明 | ユースケース | | ------------------------------------------ | --------------------------- | -------------------------------------- | | `shared_payment.granted_token.deactivated` | SPT が無効化 (失効または期限切れ) されました。 | SPT を使用できなくなったことを知るために、このイベントをリッスンします。 | # エージェント > This is a エージェント for when agent-seller is agent. View the full page at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens?agent-seller=agent. エージェントは、[共有支払いトークン (SPT)](https://docs.stripe.com/api/shared-payment/issued-token/.md) を使用して、売り手に支払い処理のための顧客の決済手段への限定アクセスを許可します。 支払い方法登録とプロセス (See full diagram at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) ## Before you begin - SPT を使用するには、[利用規約](https://stripe.com/legal/ssa-services-terms#stripe-agentic-commerce-agent-services-preview)に同意する必要があります。 - Stripe アカウントをまだお持ちでない場合には、[アカウントを作成](https://stripe.com/register)してください。 - Stripe ダッシュボードで [Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md)を作成してください。 ## 売り手から Stripe プロフィールを収集する 売り手のユーザー登録時に、売り手の Stripe プロフィールを収集します。売り手は、[Stripe ダッシュボード](https://dashboard.stripe.com/profiles)で新しいプロフィールを作成するか、現在のプロフィールを確認できます。取引ごとに、このプロフィールに SPT を発行します。 ## 顧客の支払い詳細を収集する [Payment Element](https://docs.stripe.com/payments/payment-element.md) を使用して、1 回の連携で支払い詳細を安全に収集し、複数の決済手段をサポートします。これにより、顧客に表示する決済手段が売り手によってサポートされていることが自動的に保証されます。連携を機能させるには、決済画面の URL が `http://` for ではなく `https://` rather で始まる必要があります。HTTPS を使用せずに連携をテストできますが、本番決済を受け付ける前に[有効にする](https://docs.stripe.com/security/guide.md#tls)必要があります。 ### Stripe.js を設定 Payment Element は Stripe.js の機能として自動的に使用できるようになります。決済画面に Stripe.js スクリプトを含めるには、HTML ファイルの `head` にスクリプトを追加します。常に `js.stripe.com` から Stripe.js を直接読み込むことにより、PCI 準拠が維持されます。スクリプトをバンドルに含めたり、そのコピーを自身でホストしたりしないでください。 ```html Checkout ``` 決済画面で以下の JavaScript を使用して、`Stripe` のインスタンスを作成します。 ```javascript // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>'); ``` ### Payment Element を決済ページに追加する > #### iFrame の競合 > > Payment Element を別の `iframe` 内に配置しないでください。支払い確認のために別のページにリダイレクトする必要がある決済手段と競合します。 Payment Element を決済画面に配置するコンテナーが必要です。支払いフォームで、一意の ID を持つ空の DOM ノードを作成します。 ```html
``` フォームが読み込まれたら、`mode`、`amount`、`currency`、`paymentMethodCreation` を指定して `Elements` インスタンスを作成します。`sellerDetails` を指定し、売り手の `networkBusinessProfile` を渡し、売り手がサポートする決済手段が Stripe に表示されるようにします。これにより、売り手と異なる決済手段をサポートしながら、買い手と互換性のある決済手段を表示できます。 次に、Payment Element のインスタンスを作成し、コンテナーの DOM ノードにマウントします。 ```javascript const options = { mode: 'payment', amount: 1000, currency: 'usd', paymentMethodCreation: 'manual', sellerDetails: { networkBusinessProfile: "profile_123" }, // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements to use in checkout formconst elements = stripe.elements(options); // Create and mount the Payment Element const paymentElementOptions = { layout: 'accordion'}; const paymentElement = elements.create('payment', paymentElementOptions); paymentElement.mount('#payment-element'); ``` ### 住所を収集 デフォルトでは、Payment Element は必要な請求住所の詳細のみを収集します。[税金の計算](https://docs.stripe.com/api/tax/calculations/create.md)、配送先情報を入力するなどの一部の動作では、顧客の完全な住所が必要です。次のように対応できます。 - [Address Element](https://docs.stripe.com/elements/address-element.md) を使用して、オートコンプリートとローカリゼーションの機能を利用して、顧客の完全な住所を収集します。これにより、最も正確な税金計算が可能になります。 - 独自のカスタムフォームを使用して住所の詳細を収集する。 ### PaymentMethod を作成する 顧客が支払いフォームを送信したら、`PaymentMethod` を作成し、それをサーバーに送信して SPT を作成します。 ```javascript const form = document.getElementById('payment-form'); const submitBtn = document.getElementById('submit'); const handleError = (error) => { const messageContainer = document.querySelector('#error-message'); messageContainer.textContent = error.message; submitBtn.disabled = false; } form.addEventListener('submit', async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); // Prevent multiple form submissions if (submitBtn.disabled) { return; } // Disable form submission while loading submitBtn.disabled = true; // Trigger form validation and wallet collection const {error: submitError} = await elements.submit(); if (submitError) { handleError(submitError); return; } // Create the PaymentMethod using the details collected by the Payment Element const {error, paymentMethod} = await stripe.preparePaymentMethod({ elements, params: { billing_details: { name: 'Jenny Rosen', } } }); if (error) { // This point is only reached if there's an immediate error when // creating the PaymentMethod. Show the error to your customer (for example, payment details incomplete) handleError(error); return; } // Create the Shared Payment Token const res = await fetch("/create-spt", { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({ paymentMethodId: paymentMethod.id, }), }); const data = await res.json(); // Handle any next actions or errors. See the Handle any next actions step for implementation. handleServerResponse(data); }); ``` ## 売り手に Shared Payment Token を発行する エージェントとして、顧客の決済手段と売り手の Stripe プロフィールを使用して取引の `SharedPaymentIssuedToken` を作成します。通貨、最大金額、有効期限などの制限を設定します。このリクエストでは、支払い処理のために売り手と共有する `SharedPaymentToken` ID が返されます。 ```curl curl https://api.stripe.com/v1/shared_payment/issued_tokens \ -u "<>:" \ -d payment_method=pm_1RgaZbFPC5QUO6ZCe2ekOCNX \ -d "seller_details[network_business_profile]=profile_123" \ -d "usage_limits[currency]=usd" \ -d "usage_limits[expires_at]=1751587220" \ -d "usage_limits[max_amount]=1000" \ --data-urlencode "return_url=http://example.com/agent-checkout/return" ``` ### 対応している決済手段 | 決済手段 | 利用可能状況 | | ----------------------------------------------------------- | --------------- | | [カード](https://docs.stripe.com/payments/cards/overview.md) | ✓ サポート対象 1 | | [Link](https://docs.stripe.com/payments/wallets/link.md) | ✓ サポート対象 | | [Apple Pay](https://docs.stripe.com/apple-pay.md) | ✓ サポート対象 | | [Google Pay](https://docs.stripe.com/google-pay.md) | ✓ サポート対象 | | [Klarna](https://docs.stripe.com/payments/klarna.md) | ✓ サポート対象 | | [Affirm](https://docs.stripe.com/payments/affirm.md) (制限あり) | ✓ Supported 2,3 | 1 カードネットワークとの連携により、Stripe は Mastercard の Agent Pay および Visa の Visa Intelligent Commerce プログラムを通じて発行されたトークンをお客様に代わってプロビジョニングして使用する場合があります。2 エージェントは、WebView 内でプログラムで Affirm ローン申請の UI とやり取りすることはできません。買い手がナビゲートして確認する必要があります。また、エージェントがナビゲーションを制御できないデバイスのブラウザーで Affirm の決済画面が表示されないこともあります。3 エージェントが顧客に Affirm をマーケティングする場合、エージェントは Affirm の[マーケティングコンプライアンスガイド](https://docs.affirm.com/developers/docs/compliance_and_guidelines)に従い、顧客に表示する Affirm の決済オプションに関連する Affirm の[ガイド](https://businesshub.affirm.com/hc/en-us/articles/10653174159636-Affirm-Marketing-Compliance-Guides)を使用する必要があります。 ### 次のアクションを処理する 売り手によって作成された支払いが完了する前に追加の顧客アクションが必要になると、`SharedPaymentToken` は `requires_action` ステータスに移行します。支払いで 3D セキュア認証や現地の決済手段へのリダイレクトなど、追加の顧客アクションが必要な場合は、そのアクションを処理する必要があります。カード支払いの場合、Stripe は次のような場合に 3D セキュアを自動的にトリガーします。 - 業種ガイドラインで義務付けられています。 - カード発行会社が要求します。 - 売り手が `SharedPaymentToken` を使用して `PaymentIntent` を処理しているときに要求します。 - 一部の Stripe 最適化が適用されます。 Stripe が 3D セキュアをトリガーすると、Stripe は顧客を銀行のユーザーインターフェイスにリダイレクトします。SPT が`requires_action` に移行すると、Stripe は `shared_payment.issued_token.requires_action` Webhook を送信します。サーバーで SPT を取得してください。 ```curl curl https://api.stripe.com/v1/shared_payment/issued_tokens/spt_123 \ -u "<>:" ``` ``` { "id": "spt_123", "object": "shared_payment.issued_token", "status": "requires_action", "next_action": { "type": "use_stripe_sdk", "use_stripe_sdk": { "value": "ewogICJ0eXBlIjogInN0cmlwZV8zZHN 2X2ZpbmdlcnByaW50IiwKICAic291cmNlIjogInNyY18xQThYeUwyZVp2S1lsbzJDOXhROXpSNXQiLAogICJvbmVfY2xpY2tfYXV0aCI6IHRydWUKfQ==" } } ... } ``` クライアントで、次のアクションフローを表示します。`handleNextAction` を呼び出すと、Stripe は認証ユーザーインターフェイスをポップアップモーダルに自動的に表示します。 #### JavaScript ```javascript const handleServerResponse = async (response) => { if (response.error) { // Show error from server on payment form } else if (response.status === "requires_action") { // Use Stripe.js to handle the required next action const result = await stripe.handleNextAction({ hashedValue: response.next_action.use_stripe_sdk.value }); const actionError = result && (result as any).error; if (actionError) { // Show error from Stripe.js in payment form } else { // Actions handled, show success message } } else { // No actions needed, show success message } } ``` 顧客が必要なアクションを完了すると、Stripe は `shared_payment.issued_token.active` Webhook を送信します。ただし、その間に `SharedPaymentToken` を無効にした場合は除きます。 ### SPT を取り消す 代理人はいつでも SPT を取り消すことができます。取り消しにより、売り手は SPT を使用して支払いを作成できなくなります。 ```curl curl -X POST https://api.stripe.com/v1/shared_payment/issued_tokens/spt_123/revoke \ -u "<>:" ``` ### Webhook イベントのリッスン Stripe は、以下の場合にお客様と売り手にイベントを送信します。 - 売り手が承認された SPT を使用して支払いを受け付けます。 - SPT を取り消したとします。売り手は、取り消した SPT で支払いを作成することはできません。 | イベント | 説明 | ユースケース | | --------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | | `shared_payment.issued_token.requires_action` | SPT では、売り手が決済を完了する前に追加の顧客アクションが必要です。 | このイベントをリッスンして SPT を取得し、`next_action` を調べ、必要な認証フローまたはリダイレクトフローをエージェントインターフェイスに提示します。 | | `shared_payment.issued_token.active` | 顧客は必要なアクションを完了し、SPT は決済フローを続行できます。 | このイベントをリッスンして、必要なアクションの完了後に SPT が再度使用可能であることを確認します。 | | `shared_payment.issued_token.used` | 売り手が SPT を使用すると、このイベントを受信します。 | このイベントをリッスンし、支払いが処理されたことを顧客に通知します。 | | `shared_payment.issued_token.deactivated` | SPT が無効化 (失効または期限切れ) されました。 | このイベントをリッスンして、SPT が無効になったときを追跡します。 |