# Shared Payment Token
エージェント主導の購入向けに、スコープ付きの決済認証情報を付与したり受け取ったりできます。
> Shared Payment Token (SPT) は、アメリカのエージェント、顧客、売り手が利用できます。
# エージェント
エージェントは、[共有支払いトークン (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 プロフィール](https://docs.stripe.com/get-started/account/profile.md)を作成できます。
## 売り手から 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 を返します。
SPT が正しい当事者に付与されるよう、売り手の `network_business_profile` を `seller_details` に渡してください。テスト環境では、`profile_test_61TU90nIeGjU7NNVXA6TU90m7ISQWsBxpcx9lASWWXTk` をテスト用の売り手プロフィールとして使用できます。
```curl
curl https://api.stripe.com/v1/shared_payment/issued_tokens \
-u "<>:" \
-H "Stripe-Version: 2026-04-22.preview" \
-d payment_method=pm_1RgaZbFPC5QUO6ZCe2ekOCNX \
-d "seller_details[network_business_profile]=profile_test_61TU90nIeGjU7NNVXA6TU90m7ISQWsBxpcx9lASWWXTk" \
-d "usage_limits[currency]=usd" \
-d "usage_limits[expires_at]=1798761600" \
-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 の Intelligent Commerce プログラムなどのネットワークプログラムを通じて発行されたトークンを、加盟店に代わって使用する場合があります。Stripe は、関連する取引のためにこれらのトークンをプロビジョニングして処理するため、要求されたデータをカードネットワークに送信します。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 セキュア認証をトリガーすると、顧客は銀行のユーザーインターフェースにリダイレクトされます。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 "<>:" \
-H "Stripe-Version: 2026-04-22.preview"
```
```
{
"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 をいつでも失効させて、売り手による決済作成を防ぐことができます。
```curl
curl -X POST https://api.stripe.com/v1/shared_payment/issued_tokens/spt_123/revoke \
-u "<>:" \
-H "Stripe-Version: 2026-04-22.preview"
```
### SPT のステータス
SPT は状態マシンとして機能し、状態は [status](https://docs.stripe.com/api/shared-payment/issued-token/object.md#shared_payment_issued_token_object-status) 属性を使用して追跡されます。状態は常に線形に進行するとは限らず、決済フローに応じてループする場合があります。たとえば、SPT は `active` から `requires_action` に遷移し、再び `active` に戻ることができます。SPT は `active` または `requires_action` のいずれかの状態で開始できます。
| ステータス | 定義 | 遷移先 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `active` | SPT は、エージェントが売り手に渡せる状態、または売り手が決済に使用できる状態です。 | `requires_action`、`deactivated` |
| `requires_action` | SPT では、決済を完了する前に顧客によるアクションが必要です。[next_action](https://docs.stripe.com/api/shared-payment/issued-token/object.md#shared_payment_issued_token_object-next_action) 属性は、顧客が実行する必要があるアクションを示します。 | `active`、`deactivated` |
| `deactivated` | SPT は無効化されており、新しい決済を処理できません。[deactivated_reason](https://docs.stripe.com/api/shared-payment/issued-token/object.md#shared_payment_issued_token_object-deactivated_reason) 属性は、その理由を示します。 | 遷移なし。終端状態は現在 `deactivated` です。 |
### 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 が無効になったときを追跡します。 |