Shared payment tokensPrivate preview

Shared payment tokens (SPT) help your business receive a customer’s payment method collected by an agent. The agent grants SPTs to your business with usage and expiration limits.

Create a shared payment token

As a seller, you can use test helpers to simulate receiving a SPT granted by an agent. This grants a SharedPaymentToken object. The following code example demonstrates granting your account an SPT using a test PaymentMethod and simulating limits that agents may specify such as currency, maximum amount, and expiration window.

curl https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens \
  -u 
"sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -d payment_method=pm_card_visa \
  -d "usage_limits[currency]"=usd \
  -d "usage_limits[max_amount]"=10000 \
  -d "usage_limits[expires_at]"={{TIME_IN_FUTURE}} \
  -d "seller_details[network_id]"=internal \
  -d "seller_details[external_id]"={{ANY_STRING}}

Usage limits

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

Seller details

The seller_details parameter sets the scope of 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 the external_id to scope the SPT to a connected account.

Payment method

The payment_method parameter specifies the payment method selected by the customer to use for the purchase.

Use a shared payment token

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

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

When you confirm a PaymentIntent with an SPT, we set 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.

curl https://api.stripe.com/v1/shared_payment/granted_tokens/{id} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

{
  "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.