Shared payment tokensPrivate preview

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.

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

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.

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

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.