# Shared payment tokens

Learn how to use shared payment tokens.

Use shared payment tokens (SPTs) to receive a customer’s payment method from an agent. The agent grants SPTs to your account with usage and expiration limits.
Payment method registration and processing (See full diagram at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens)
## Create a shared payment token

As a seller, use test helpers to simulate receiving an SPT granted by an agent. This request returns a `SharedPaymentToken` object. The following example grants your account an SPT using a test payment method and simulates limits that agents might set, such as currency, maximum amount, and expiration window.

```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]"=1776516041\
  -d "seller_details[network_id]"=internal \
  -d "seller_details[external_id]"={{ANY_STRING}}
```

### Set usage limits

Use the `usage_limits` parameter to specify the maximum amount and expiration window. The agent sets the maximum amount to match the total amount of the transaction.

### Set seller details

Use the `seller_details` parameter to scope the SPT to you or another seller.

- `network_id`: The seller’s network ID.
- `external_id`: An optional identifier that links the SPT to a specific seller, cart, or other identifier. For example, an agent interacting with a Connect platform might use `external_id` to scope the SPT to a connected account.

### Specify the payment method

Use the `payment_method` parameter to specify the payment method the customer selected for the purchase.

## Use a shared payment token

After you receive a granted `SharedPaymentToken`, create a `PaymentIntent` to complete the payment.

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

When you confirm a `PaymentIntent` with an SPT, Stripe sets `payment_method` to a new `PaymentMethod` cloned from the customer’s original method. Subsequent events, such as refunds and reporting, behave as if you provided the `PaymentMethod` directly. You can retrieve details about the granted `SharedPaymentToken`, including limited information about the underlying payment method (for example, card brand and last four digits) and its usage limits.

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

### Listen for webhook events 

We send events to you and the agent when:

- You use a granted SPT to accept a payment.
- The agent revokes a granted SPT. You can’t create a payment with a revoked SPT.

| Event                                      | Description | Received by                                         | Use case                                                                                     |
| ------------------------------------------ | ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `shared_payment.granted_token.used`        | You         | You receive this event when the SPT has been used.  | Listen for this event to confirm that the SPT has been used.                                 |
| `shared_payment.granted_token.deactivated` | You         | The SPT has been deactivated (revoked or expired).  | Listen for this event to know when an SPT can no longer be used.                             |
| `shared_payment.issued_token.used`         | Agent       | The agent receives this event when you use the SPT. | The agent listens for this event to notify the customer that the payment has been processed. |
| `shared_payment.issued_token.deactivated`  | Agent       | The SPT has been deactivated (revoked or expired).  | The agent listens for this event to track when an SPT is no longer valid.                    |