Unlocking Stripe Shared Payment Tokens for Secure Transactions

▶ Watch the 60-second version on YouTube

Introducing Stripe Shared Payment Tokens (SPTs)

In a world where data breaches are rampant, the need for secure transaction models has never been more critical. Stripe's Shared Payment Tokens (SPTs) offer a robust solution to this problem by allowing agents to perform transactions without ever exposing raw card numbers. SPTs are scoped, merchant-locked, and time-limited, making them ideal for applications that require enhanced security. This functionality was expanded at Sessions 2026, and it’s time to dive into how you can leverage SPTs in your payment processes.

How SPTs Work

SPTs act as a shield for sensitive card information. They allow your application to generate a token that can be used by agents to make payments on behalf of customers. The key features of SPTs include:

• Scoped: Tokens can be limited to specific actions or types of payments.
• Merchant-Locked: Tokens are tied to a specific merchant account, ensuring that they can't be misused elsewhere.
• Time-Limited: Tokens expire after a defined period, reducing the window of opportunity for malicious actors.

Setting Up Shared Payment Tokens

To set up SPTs, you will need to ensure that your Stripe account is configured correctly. Here's a step-by-step breakdown:

1. Create a Payment Method

First, you'll need to create a payment method for your customer. You can do this via the Stripe API:

import stripe

stripe.api_key = "your_secret_key"

# Create a payment method
payment_method = stripe.PaymentMethod.create(
    type="card",
    card={
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2023,
        "cvc": "123",
    },
)

2. Generate a Shared Payment Token

Next, use the payment method to generate a Shared Payment Token:

# Generate a Shared Payment Token (SPT)
spt = stripe.PaymentIntent.create(
    amount=1000,
    currency="usd",
    payment_method=payment_method.id,
    confirmation_method="manual",
    confirm=True,
)
print(f"Shared Payment Token: {spt.id}")

3. Use the SPT for Transactions

Once you have the SPT, you can use it for transactions within your application. Each time you use the token, you can specify the scope and conditions under which it can be used.

Handling Expiry and Permissions

One of the most crucial aspects of working with SPTs is managing their lifecycle effectively. Tokens have a limited timeframe during which they can be utilized. Be sure to implement checks in your application to handle expired tokens gracefully. If you attempt to use an expired SPT, you'll receive a 404 error, so ensure you catch this in your application logic.

Non-Obvious Gotcha: Token Scope and Permissions

One area that often trips developers up is the concept of token scope. It's essential to understand that while SPTs are merchant-locked, they can also be scoped to specific actions or types of payments. If you're building a platform that allows multiple merchants to use SPTs, make sure to tailor the permissions accordingly. For example, if a merchant A can only authorize transactions up to $50, and you attempt to use the token for a $100 transaction, it will fail.

To manage this effectively, always validate the token scope and permissions before making a transaction. This ensures that the token is being used within the defined parameters set during its creation.

Integrating with Other Services

SPTs work well with various services like Stripe Treasury, where you can manage funds and balances, or with platforms like Plaid for enhanced user authentication and account linking. For instance, you can create a seamless user experience by combining SPTs with Plaid’s API to pull in user bank account information securely.

Example: Using SPTs with Plaid

# Assuming you have obtained a Plaid access token
plaid_access_token = "your_plaid_access_token"

# Fetch the user's bank account details
response = plaid.Client().accounts.get(plaid_access_token)
accounts = response['accounts']

# Create a payment using the SPT
if accounts:
    spt_payment = stripe.PaymentIntent.create(
        amount=5000,
        currency="usd",
        payment_method=spt.id,
        confirm=True,
    )
    print(f"Payment successful: {spt_payment.id}")

Final Thoughts

Stripe Shared Payment Tokens provide an elegant solution for securing transactions in your application. By utilizing scoped, merchant-locked, and time-limited tokens, you can significantly reduce the risks associated with raw card number exposure. As you implement SPTs, keep in mind the importance of token lifecycle management and the non-obvious nuances of scope and permissions. With these considerations in mind, you can build a secure and robust payment system that protects both your users and your business.