Skip to main content
Shared Payment Tokens (SPTs) are Stripe’s mechanism for agent-facilitated commerce. An SPT is a temporary, scoped payment credential granted by an AI agent on behalf of a customer. SPTs allow Orb to collect payment without requiring the customer to have a stored payment method on file. For more on SPTs from Stripe, see Stripe’s SPT documentation.
This feature requires enablement on your account. Contact your Orb account team to get started.

​
How it works

  1. An AI agent, acting on behalf of a customer, negotiates a purchase
  2. The agent grants an SPT to you (the seller/merchant) via Stripe’s agentic commerce API
  3. You configure the SPT on the customer in Orb
  4. Orb uses the SPT to collect payment, either on-demand or via auto-collection
When Orb creates a PaymentIntent with an SPT, Stripe handles the payment using credentials carried by the token, which resolves to a Payment Method in Stripe.

​
Prerequisites

  • A Stripe Connect integration with Orb
  • The feature enabled on your account
  • An SPT ID (formatted as spt_...) obtained through Stripe’s agentic commerce flow

​
Configuring a default SPT on a customer

Set a default SPT on a customer so Orb uses it for auto-collection: 
curl https://api.withorb.com/v1/customers/{customer_id} \
  -X PUT \
  -H "Authorization: Bearer $ORB_API_KEY" \
  -d '{
    "payment_configuration": {
      "payment_providers": [{
        "provider_type": "stripe",
        "default_shared_payment_token": "spt_..."
      }]
    }
  }'
To clear a stored SPT: 
curl https://api.withorb.com/v1/customers/{customer_id} \
  -X PUT \
  -H "Authorization: Bearer $ORB_API_KEY" \
  -d '{
    "payment_configuration": {
      "payment_providers": [{
        "provider_type": "stripe",
        "default_shared_payment_token": null
      }]
    }
  }'
You can also set or clear the SPT from the Orb dashboard via the Edit customer details dialog under the Payments section.

​
Collecting payment

​
Auto-collection with a stored SPT

When a customer has a default SPT configured, Orb will automatically use it for invoice auto-collection. The SPT always takes priority over the customer’s default payment method in Stripe. If the SPT fails at charge time, the invoice payment will fail. Orb does not clear the stored SPT automatically or fall back to the customer’s default payment method, because this would provide a way to circumvent the limits of the SPT. The SPT must always be cleared by your integration.
If the SPT has not been deactivated explicitly (e.g. it’s exhausted temporarily), you may choose to keep the SPT as the payment method and increase the maximum allowance, or prompt your end-user to do so.

​
One-off payment with an SPT

You can pay a specific invoice with an SPT without storing it on the customer: 
curl https://api.withorb.com/v1/invoices/{invoice_id}/pay \
  -X POST \
  -H "Authorization: Bearer $ORB_API_KEY" \
  -d '{
    "shared_payment_token_id": "spt_..."
  }'
If no request body is provided, the endpoint falls back to the customer’s default payment method (existing behavior).

​
SPT lifecycle

​
Reuse

SPTs support recurring use within Stripe’s mandate limits. A single token can be used for multiple PaymentIntents over time. Stripe enforces a maximum amount — multiple charges are allowed within that limit if it’s a recurring shared payment token.

​
Expiration and deactivation

Stripe manages SPT expiry. When a token is deactivated (revoked by the agent or expired), Stripe sends a shared_payment.granted_token.deactivated webhook. Orb processes this event and logs it. We also encourage you to listen for this webhook to clear the payment token in Orb. If a deactivated or exhausted SPT is used at charge time, Stripe will reject the PaymentIntent synchronously. Orb handles this as a terminal failure for the invoice collection process.

​
Dunning

Orb does not start a dunning schedule when an SPT payment fails. Orb also does not clear SPTs automatically to prevent policy bypass.

​
What’s supported

CapabilityStatus
Store a default SPT on a customerSupported
Auto-collection using stored SPTSupported
One-off invoice payment with SPTSupported
Automatic fallback on SPT failureNot supported — Orb does not fall back to other payment methods to avoid bypassing SPT policies
Dunning after SPT failureNot supported
Invoice portal (customer-initiated payment)Not applicable — SPTs are for off-session, agent-facilitated payments
SPT as a payment method in customer portalNot supported — SPTs are managed via API or dashboard, not self-service
If an SPT payment fails, it will not trigger dunning. Orb will also not fall back to other payment methods to avoid bypassing purpose-set SPT policies.

​
Integration guide

​
Step 1: Obtain an SPT

A customer’s agent grants a shared payment token (spt_...) to your Stripe account through Stripe’s agentic commerce API. This happens outside of Orb. Refer to Stripe’s SPT documentation for details.

​
Step 2: Store the SPT on a customer

Set the SPT as the default payment instrument for a customer via the Orb API, as outlined above.

​
Step 3: Invoices are auto-collected using the SPT

No additional integration is needed. When an invoice is issued for a customer with a stored SPT, Orb will automatically use it for payment collection. The SPT takes priority over the customer’s default payment method.

​
Step 4 (optional): Pay a specific invoice with an SPT

To pay a single invoice without storing the SPT on the customer, use the /pay endpoint.

​
Step 5: Handle webhooks

Register for the following Stripe webhook events and forward them to Orb as you do today:
EventDescription
shared_payment.granted_token.usedConfirms the SPT was used for a payment
shared_payment.granted_token.deactivatedThe SPT has been permanently revoked
Orb logs these events. When a deactivated SPT is used for payment, Stripe will reject the charge synchronously. Orb will not automatically clear the stored SPT — your integration should clear it via the API when you receive a deactivation event, or when the agent grants a replacement token.

​
Step 6: Manage the SPT lifecycle

Orb does not automatically clear stored SPTs. Your integration is responsible for:
  • Clearing a deactivated SPT: Update the customer with "default_shared_payment_token": null when you receive a deactivation webhook or know the token is no longer valid
  • Replacing an exhausted SPT: If the token’s monthly limit is reached, Stripe will reject charges until the limit resets. You can either wait for the reset or have the agent grant a new token
  • Removing an SPT to revert to normal payment: Set "default_shared_payment_token": null to resume using the customer’s default payment method

​
FAQ

Can I use an SPT alongside a regular payment method? Yes. The SPT takes priority for auto-collection when set. If the SPT fails, Orb will not fall back to the customer’s default payment method — the invoice payment will simply fail. To revert to regular payment method behavior, clear the SPT via the API or dashboard. What happens if the SPT’s monthly limit is reached? The PaymentIntent creation will fail synchronously. Orb will not clear the stored SPT since it’s not deactivated, and dunning will not activate on the invoice. Do I need to clear the SPT manually when it’s deactivated? Yes. You can clear it via the API or dashboard. Can I validate an SPT before storing it? Yes, you can do this on the client-side but Orb does not do this for you. If an invalid SPT ID is stored, it will fail at charge time.