# Shared payment tokens

Grant and receive scoped payment credentials for agent-initiated purchases.

Shared payment tokens (SPTs) grant sellers scoped access to customers’ payment methods for agent-initiated purchases. SPTs are available to agents, customers, and sellers in the US, Canada, and select European countries.

### View all supported countries

- AT
- BE
- BG
- CA
- CH
- CY
- CZ
- DE
- DK
- EE
- ES
- FI
- FR
- GB
- GI
- GR
- HR
- HU
- IE
- IT
- LI
- LT
- LU
- LV
- MT
- NL
- NO
- PL
- PT
- RO
- SE
- SI
- SK
- US

# Sellers


As the seller, you receive a [shared payment token (SPT)](https://docs.stripe.com/api/shared-payment/granted-token.md) from the agent. An SPT is a scoped grant to use the customer’s payment method. The agent grants SPTs to your [Stripe profile](https://docs.stripe.com/get-started/account/profile.md), each with usage and expiration limits.

Payment method registration and processing (See full diagram at https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens)

```text
[Customer] -- Submits PaymentMethod --> [Agent]
[Agent] -- Issues SharedPaymentToken --> [Stripe]
[Agent] -- Sends SharedPaymentToken --> [Seller]
[Seller] -- Creates PaymentIntent with SharedPaymentToken --> [Stripe]
[Stripe] -- Processes transaction --> [Customer]
```

## Before you begin

- By using SPTs, you agree to the [terms of service](https://stripe.com/legal/ssa-service-terms#stripe-agentic-commerce-seller-services-preview).
- If you don’t already have a Stripe account, [create one](https://stripe.com/register).
- Create your [Stripe profile](https://docs.stripe.com/get-started/account/profile.md) in the Dashboard.

## Test receiving an SPT

Use test helpers to simulate receiving an SPT granted by the agent. The following request 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>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d payment_method=pm_card_visa \
  -d "usage_limits[currency]=usd" \
  -d "usage_limits[max_amount]=1000" \
  -d "usage_limits[expires_at]=1798761600"
```

### 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.

### Specify the payment method

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

## Test your live mode integration

To test your integration in live mode, use the [link-cli](https://link.com/agents) to issue SPTs from your personal Link account. The `link-cli` can provision one-time shared payment token credentials. Follow the instructions at [link.com/agents](https://link.com/agents) to install the `link-cli` skills or register it as an MCP server in your preferred agent.

1. Log in to your personal Link account, or [sign up](https://app.link.com) if you don’t have one.

```bash
npx @stripe/link-cli auth login
```

1. Choose the payment method you want to use. If you don’t already have one, [add a payment method](https://app.link.com/wallet).

```bash
npx @stripe/link-cli payment-methods list
```

1. Create a spend request to issue a one-time SPT scoped to your Stripe profile. The `--amount` value is in the currency’s smallest unit (for example, `100` is 1.00 USD).

```bash
npx @stripe/link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --context "Test purchase to confirm that my business can accept a one-time shared payment token issued by link-cli in live mode" \
  --amount 100 \
  --credential-type shared_payment_token \
  --network-id profile_xxx \
  --request-approval
```

## Use a shared payment token

After you receive a granted `SharedPaymentToken`, you can process the payment with Stripe or [use the SPT with a third-party processor](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md#resolve). To process the payment with Stripe, create a `PaymentIntent`.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_data[shared_payment_granted_token]=spt_123" \
  -d confirm=true
```

When you confirm a `PaymentIntent` with the SPT, Stripe sets `payment_method` to a new `PaymentMethod` cloned from the customer’s original payment method. Subsequent events, such as refunds and reporting, behave as if you provided the `PaymentMethod` directly.

Retrieve details about the granted `SharedPaymentToken`, including limited information about the underlying payment method, such as the card brand (`payment_method_details.card.brand`), last four digits (`payment_method_details.card.last4`), and `usage_limits`.

```curl
curl https://api.stripe.com/v1/shared_payment/granted_tokens/spt_123 \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview"
```

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

## Use an SPT with a third-party processor 

Use the SPT Resolve API to retrieve network credentials and submit them to your payment processor.

```curl
curl -X POST https://api.stripe.com/v1/shared_payment/granted_tokens/spt_123/resolve \
  -u "<<YOUR_SECRET_KEY>>:"
```

```text
{
  id: "spt_123",
  object: "shared_payment.granted_token",
  created: 1782172800,
  deactivated_at: null,
  deactivated_reason: null,
  livemode: true,
  shared_metadata: {},
  payment_method_details: {
    type: "card",
    card: {
      credentials?: {
        type: "dpan" || "agentic_token" || "fpan",
        // if type is agentic_token
        agentic_token?: {
          number?: string,
          exp_month?: string,
          exp_year?: string,
          cryptogram?: {
            value: string,
            type: "CAVV" | "TAVV" | "DCVV",
            eci?: string
          },
          encrypted?: {
            encryption_type: "RSA",
            encryption_block: string,
            encryption_block_fields: string,
            key_id: string
          }
        },
        // if type is dpan
        dpan?: {
          number?: string,
          exp_month?: string,
          exp_year?: string,
          cryptogram?: {
            value: string,
            type: "CAVV" | "TAVV" | "DCVV",
            eci?: string
          },
          encrypted?: {
            encryption_type: "RSA",
            encryption_block: string,
            encryption_block_fields: string,
            key_id: string
          }
        },
        // if the type is fpan
        fpan?: {
          number?: string,
          exp_month?: string,
          exp_year?: string,
          cvc?: string,
          encrypted?: {
            encryption_type: "RSA",
            encryption_block: string,
            encryption_block_fields: string,
            key_id: string
          }
        }
      },
      brand: "visa",
      country: "US",
      display_brand: "visa",
      exp_month: 9,
      exp_year: 2029,
      fingerprint: "dyRcYjZNxnHpC51l",
      funding: "credit",
      last4: "5627",
      networks: {
        available: ["visa"],
        preferred: null
      },
      wallet: null
    }
  },
  usage_details: {
    amount_captured: {
      value: 1000,
      currency: "usd"
    }
  },
  usage_limits: {
    currency: "usd",
    expires_at: 1798761600,
    max_amount: 10000
  },
  agent_details: {
    name: string,
    network_business_profile: "profile_1234"
  }
}
```

The API returns one of four credential types in `payment_method_details.card.credentials.type`:

- `fpan`
- `network_token`
- `agentic_token`
- `dpan`

Stripe returns a credential type based on your account’s credential configuration and the payment method backing the SPT.

> In collaboration with the card networks, Stripe might use tokens issued through network programs such as Mastercard’s Agent Pay, Visa’s Intelligent Commerce, and American Express ACE Kit on your behalf. Stripe submits the requested data to the card networks to provision and process those tokens for related transactions.

### Record a payment 

After you capture the payment with your processor, record a [payment](https://docs.stripe.com/api/payment-record/report.md) and confirm the checkout flow.

```curl
curl https://api.stripe.com/v1/payment_records/report_payment \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_details[shared_payment_granted_token]=spt_123" \
  -d "amount_requested[value]=1000" \
  -d "amount_requested[currency]=usd" \
  -d initiated_at=1782172800 \
  -d outcome=guaranteed \
  -d "guaranteed[amount][value]=1000" \
  -d "guaranteed[amount][currency]=usd" \
  -d "guaranteed[final_capture]=true" \
  -d "guaranteed[guaranteed_at]=1782172800" \
  -d "processor_details[type]=custom" \
  -d "processor_details[custom][payment_reference]=auth_order_id_1"
```

### Configure resolution behavior 

Because the SPT Resolve API handles sensitive data, Stripe configures its behavior for your account. The configuration determines:

- **Encryption**: Whether Stripe encrypts each credential type.
- **Encrypted fields**: Which fields Stripe encrypts for each credential type.

The API returns encrypted fields in the `encrypted` property for the credential type. Encryption works as follows:

- `encryption_type`: The method Stripe used to encrypt the data. This value matches your credential configuration.
- `encryption_block`: The encrypted credential data.
- `encryption_block_fields`: The layout of the data in `encryption_block`. Each comma-separated entry uses the format `<field_name>:<start_index>:<length>`.
- `key_id`: The identifier for the encryption key.

You can only resolve an SPT one time.

#### Handle errors

The API returns a `400` error in the following cases:

- Stripe hasn’t created a credential configuration for your account
- You previously resolved the SPT
- You previously used the SPT in a PaymentIntent
- Stripe can’t resolve the payment method into a usable credential

### Meet PCI requirements 

If you haven’t provided Stripe with your PCI Attestation of Compliance, Stripe must encrypt credentials that fall within PCI scope. Stripe encrypts these credentials with a public key whose corresponding private key you can’t access. For example, Stripe can use a public key owned by your payment processor.

If you’re PCI compliant, you must provide Stripe with your [PCI Attestation of Compliance](https://stripe.com/en-ca/guides/pci-compliance).

## Listen for webhook events 

We send events to you and the agent when:

- You use a granted SPT to accept a payment.
- You resolve a granted SPT for use with a third-party processor.
- The agent revokes a granted SPT. You can’t create a payment with a revoked SPT.

Verify webhook signatures to confirm that events come from Stripe. Learn how to [verify events](https://docs.stripe.com/webhooks.md#verify-events).

| Event                                      | Description                                                             | Use case                                                          |
| ------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `shared_payment.granted_token.deactivated` | The SPT has been deactivated (consumed, resolved, expired, or revoked). | Listen for this event to know when you can no longer use the SPT. |