# 共有決済トークン

共有決済トークンの使い方をご紹介します。

共有決済トークン (SPT) を使用して、エージェントから顧客の決済手段を受け取ります。エージェントは、使用状況と有効期限の制限付きで SPT をアカウントに付与します。
支払い方法登録とプロセス (See full diagram at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens)
## 共有決済トークンの作成

売り手は、テストヘルパーを使用して、エージェントによって付与された SPT の受け取りをシミュレーションできます。これにより、`SharedPaymentToken` オブジェクトが付与されます。次の例では、テスト用の決済手段を使用してアカウントに SPT を付与し、通貨、最大金額、有効期限など、エージェントが指定できる制限をシミュレーションする方法を示します。

```curl
curl https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens \
  -u "<<YOUR_SECRET_KEY>>": \
  -d payment_method=pm_card_visa \
  -d "usage_limits[currency]"=usd \
  -d "usage_limits[max_amount]"=10000 \
  -d "usage_limits[expires_at]"=1776926901
```

### 使用状況制限の設定

`usage_limits` パラメータを使用して最大金額と有効期限を指定します。エージェントは、取引の合計金額と一致するように最大金額を設定します。

### 決済手段の指定

`payment_method` パラメータを使用して、顧客が購入に選択した決済手段を指定します。

## 共有支払いトークンの使用

付与された `SharedPaymentToken` を受け取ったら、`PaymentIntent` を作成して決済を完了します。

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=10000 \
  -d currency=usd \
  -d shared_payment_granted_token=spt_123 \
  -d confirm=true
```

SPT で `PaymentIntent` を確定すると、Stripeにより顧客の元の決済手段から複製された新しい `PaymentMethod` に `payment_method` が設定されます。返金やレポート作成などの後続のイベントは、`PaymentMethod` を直接指定したかのように動作します。付与された `SharedPaymentToken` の詳細を取得できます。これには、使用する決済手段に関する制限付き情報 (カードブランドや末尾 4 桁など) および使用状況の制限が含まれます。

```bash
curl https://api.stripe.com/v1/shared_payment/granted_tokens/{id} \
  -u "<<YOUR_SECRET_KEY>>:"
```

```json
  {
  "id": "spt_1RgaZcFPC5QUO6ZCDVZuVA8q",
  "object": "shared_payment.granted_token",
  "created": 1751500820,
  "deactivated_at": null,
  "deactivated_reason": null,
  "usage_limits": {
    "currency": "usd",
    "expires_at": 1751587220,
    "max_amount": 1000
  }
}
```

### Webhook イベントのリッスン

Stripe は、以下の場合にお客様とエージェントにイベントを送信します。

- 承認された SPT を使用して決済を受け付けます。
- エージェントは許可された SPT を取り消します。取り消した SPT で決済を作成することはできません。

| イベント                                       | 説明  | 受信者                                | ユースケース                                    |
| ------------------------------------------ | --- | ---------------------------------- | ----------------------------------------- |
| `shared_payment.granted_token.used`        | お客様 | このイベントは、SPT が使用されたときに受信されます。       | このイベントを受信して、SPT が使用されたことを確認してください。        |
| `shared_payment.granted_token.deactivated` | お客様 | SPT が無効化 (失効または期限切れ) されました。        | SPT が使用できなくなったことを知るために、このイベントをリッスンします。    |
| `shared_payment.issued_token.used`         | 代理店 | エージェントは、SPT を使用したときに、このイベントを受信します。 | エージェントはこのイベントをリッスンし、決済が処理されたことを顧客に通知します。  |
| `shared_payment.issued_token.deactivated`  | 代理店 | SPT が無効化 (失効または期限切れ) されました。        | エージェントはこのイベントをリッスンして、SPT が無効になった時点を追跡します。 |