com.agentscore.payment.stripe_spt v1

1. Introduction

Stripe Shared Payment Token (SPT): agent-minted, merchant-scoped. Lets agents pay with a Stripe-managed funding source without sharing raw payment credentials.

AgentScore binding for Stripe Shared Payment Tokens (SPT) in UCP. SPTs let the agent pay with a Stripe-managed funding source (card, bank, Link wallet) without sharing raw payment credentials. The agent mints an SPT on its own Stripe account scoped to the merchant's profile id, presents it on the 402 retry, and the merchant captures the PaymentIntent server-side. Funding-source variety (own Stripe account, Link CLI, etc.) lives at the client/instruction layer (the 402 body's `agent_instructions.how_to_pay.stripe_spt` and `compatible_clients.stripe_spt`), not in this rail config.

2. Configuration

The schema for the binding's `config` object lives at /schemas/payment-handlers/stripe_spt.json. The wrapper fields (id, version, spec, schema, config) are defined by UCP itself.

Fields:

• rail (string (const)): Always `stripe-spt` (kebab-case rail identifier; distinct from the snake_case UCP namespace key).
• profile_id (string): Stripe profile id; the merchant-side network identifier the agent's SPT is scoped to.

Example config:

{
  "rail": "stripe-spt",
  "profile_id": "profile_5xKvNqM9BaH"
}

3. Payment protocol

End-to-end flow from the merchant's 402 challenge to settlement:

1. 402 emit. Merchant returns 402 with accepts[] including a stripe-spt entry carrying the merchant's profile_id. The 402 body also carries agent_instructions.how_to_pay.stripe_spt with the SPT mint instructions and the merchant's profile id.
2. Agent prep. Agent (or its wallet) calls Stripe's Issue Shared Payment Token API on the AGENT's Stripe account, scoped to the merchant's profile_id, with a single-use nonce + amount. Stripe returns the SPT string.
3. Retry. Agent re-POSTs the original request with the SPT in the configured header (X-Stripe-Spt is the common convention).
4. Capture. Merchant calls paymentIntents.create with the SPT + idempotency key. Stripe verifies scope, captures funds, and returns the PaymentIntent.
5. Settle. Merchant returns 200 + the original resource. On declined SPT (insufficient funds, scope mismatch) returns 402 with the decline reason.

4. Server processing

Merchant-side responsibilities once the agent's payment credential arrives on the retry leg:

1. Receive the SPT from the agent's payment header (typically X-Stripe-Spt).
2. Call stripe.paymentIntents.create({ shared_payment_token, amount, currency, ... }) server-side. Stripe verifies the SPT is scoped to the merchant's profile_id and returns a PaymentIntent.
3. Confirm the PaymentIntent. On success Stripe captures the funds from the agent's Stripe-managed source.
4. Capture the PaymentIntent id for the order record. Idempotency: set the SPT's nonce as the idempotency key so retries don't double-charge.

5. Security considerations

• SPTs are scoped to a specific merchant profile_id. The merchant's Stripe account validates the scope server-side; an SPT minted for profile_A cannot be redeemed by merchant_B.
• SPTs are single-use by default. Stripe rejects replay. The merchant should still set the idempotency key on paymentIntents.create so a retry from the same agent against the same SPT is safe.
• Never log the raw SPT in plaintext: it functions as a bearer credential between issue and capture. Log only the resulting PaymentIntent id for traceability.

See also

• Reference agent client: agentscore-pay (npm: @agent-score/pay). See docs.agentscore.com/integrations/pay-cli
• Merchant SDKs: @agent-score/commerce (Node) and agentscore-commerce (Python)
• UCP payment-handler guide: ucp.dev/specification/payment-handler-guide