Stripe charge Intent for HTTP Payment Authentication

Stripe charge Intent for HTTP Payment Authentication Tempo Labs

brendan@tempo.xyz

Stripe

stevekaliski@stripe.com

This document defines the "charge" intent for the Stripe payment method within the Payment HTTP Authentication Scheme . It specifies how clients and servers exchange one-time payments using Stripe Payment Tokens (SPTs).

Introduction This specification defines the "charge" intent for use with the Stripe payment method in the Payment HTTP Authentication Scheme . The charge intent enables one-time payments where the server processes the payment immediately upon receiving a Stripe Payment Token (SPT). Stripe provides payment processing through SPTs, which are single-use tokens that represent payment authorization. SPTs abstract away the complexity of payment method details (cards, bank accounts, wallets) and provide a unified interface for payment acceptance.

Stripe Charge Flow The following diagram illustrates the Stripe charge payment flow:

Relationship to the Payment Scheme This document is a payment method intent specification as defined in . It defines the request and payload structures for the charge intent of the stripe payment method, along with verification and settlement procedures.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Stripe Payment Token (SPT): A single-use token (prefixed with spt_) that represents authorization to charge a payment method. SPTs are created by clients using the Stripe API and consumed by servers to process payments. Both the Client and Server require a Stripe account. In the Stripe API, SPTs are referenced as shared_payment_granted_token on PaymentIntent creation. Learn more: https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens
Business Network Profile: A Stripe profile is a business’s public identity on Stripe. With a Stripe profile, businesses can find, verify, and connect with each other on Stripe. Learn more: https://docs.stripe.com/get-started/account/profile
Payment Intent: A Stripe API object that tracks the lifecycle of a customer payment, from creation through settlement. Not to be confused with the HTTP Payment Auth protocol's "payment intent" parameter. Learn more: https://docs.stripe.com/payments/payment-intents

Intent Identifier This specification defines the following intent for the stripe payment method:

The intent identifier is case-sensitive and MUST be lowercase.

Intent: "charge" A one-time payment of the specified amount. The server processes the payment immediately upon receiving the SPT. Fulfillment mechanism: Stripe Payment Token (SPT): The payer creates an SPT using the Stripe API, which the server uses to create a PaymentIntent via Stripe.

Request Schema The request parameter in the WWW-Authenticate challenge contains a base64url-encoded JSON object with the following fields. The JSON MUST be serialized using JSON Canonicalization Scheme (JCS) before base64url encoding, per .

Shared Fields Field Type Required Description amount string REQUIRED Amount in smallest currency unit (e.g., cents), encoded as a string currency string REQUIRED Three-letter ISO currency code (e.g., "usd") description string OPTIONAL Human-readable payment description externalId string OPTIONAL Merchant's identifier (e.g., order ID, cart ID) recipient string OPTIONAL Payment recipient identifier

Method Details Field Type Required Description methodDetails.networkId string REQUIRED Stripe Business Network Profile ID methodDetails.paymentMethodTypes []string REQUIRED The list of payment method types that the seller can process. methodDetails.metadata object OPTIONAL Key-value pairs for additional context Example:

The client fulfills this by creating an SPT using Stripe:

Credential Schema The Payment credential is a base64url-encoded JSON object containing challenge and payload fields per . For Stripe charge, the payload object contains the following fields: Field Type Required Description spt string REQUIRED Stripe Payment Token ID (starts with spt_) externalId string OPTIONAL Client's reference ID Example:

Verification Procedure Servers MUST verify Payment credentials for charge intent: Verify the challenge ID matches the one issued Verify the challenge has not expired Extract the spt from the credential payload Verify the SPT has not been previously used (replay protection) Validate the SPT exists and is valid via Stripe API (optional pre-check) Servers MUST complete challenge ID validation and expiry checks (steps 1-2) before processing credential material (steps 3-5). This ensures basic request validity is established before accessing payment tokens.

Challenge Binding Servers MUST verify that the credential corresponds to the exact challenge issued. This includes validating: Challenge ID Amount (if specified in request) Currency Business Network (if specified) Any custom metadata

Settlement Procedure Synchronous settlement: Server receives and verifies the credential () Server creates a Stripe PaymentIntent with confirm: true and the SPT as shared_payment_granted_token:

Server MUST verify the PaymentIntent status is "succeeded" before returning 200 with Payment-Receipt header If the PaymentIntent fails or requires additional action, server returns 402 with a new challenge Idempotency: Servers SHOULD include an idempotency key derived from the challenge ID and SPT when creating PaymentIntents. This prevents duplicate charges if the client retries a request. Settlement timing: Stripe processes fund transfers asynchronously. Servers SHOULD return 200 immediately after PaymentIntent confirmation (status "succeeded"), even if final fund settlement to the merchant is pending.

Receipt Generation Upon successful settlement, servers MUST return a Payment-Receipt header per . Servers MUST NOT include a Payment-Receipt header on error responses; failures are communicated via HTTP status codes and Problem Details. The receipt payload for Stripe charge: Field Type Description method string "stripe" reference string Stripe PaymentIntent ID (e.g., "pi_1N4...") status string "success" timestamp string confirmation time externalId string OPTIONAL. Echoed from credential payload

Security Considerations

SPT Single-Use Constraint SPTs are single-use tokens. Stripe automatically prevents SPT reuse at the API level, and idempotency keys () prevent duplicate PaymentIntent creation. Servers MUST enforce single-use challenge IDs per and SHOULD use Stripe idempotency keys to prevent repeated charges. Servers MAY additionally maintain a local replay cache of consumed challenge IDs.

Amount Verification Clients MUST verify the payment amount in the challenge matches their expectation before creating an SPT. The SPT itself does not encode the amount, so clients must trust the challenge parameters. Verification checklist: Verify the amount matches the expected cost Verify the currency matches the expected currency Verify the description matches the expected service Verify the challenge hasn't expired Verify the server's identity (TLS certificate validation)

PCI DSS Compliance Stripe's SPT model ensures clients never handle raw payment method details, significantly reducing PCI DSS compliance scope.

HTTPS Requirement All communication MUST use TLS 1.2 or higher. Stripe Payment Tokens MUST only be transmitted over HTTPS connections.

IANA Considerations

Payment Intent Registration This specification registers the "charge" intent for the "stripe" payment method in the Payment Intent Registry established by : Intent: charge Method: stripe Specification: [this document] Contact: Stripe (stevekaliski@stripe.com) and Tempo Labs (brendan@tempo.xyz)

&RFC2119; &RFC3339; &RFC8174; &RFC8785; &RFC7235; The 'Payment' HTTP Authentication Scheme Stripe API Reference Stripe, Inc.

ABNF Collected

Examples

Charge Example (HTTP Transport) Step 1: Client requests resource

Step 2: Server issues payment challenge

Decoded request: ~~~ json { "amount": "5000", "currency": "usd", "description": "AI generation" } ~~~ Step 3: Client creates SPT and submits credential

Decoded credential: ~~~ json { "challenge": { "id": "ch_1a2b3c4d5e", "realm": "api.example.com", "method": "stripe", "intent": "charge", "request": "eyJhbW91bnQiOiI1MDAwIiwiY3VycmVuY3kiOiJ1c2QiLCJkZXNjcmlwdGlvbiI6IkFJIGdlbmVyYXRpb24ifQ", "expires": "2025-01-15T12:05:00Z" }, "payload": { "spt": "spt_1N4Zv32eZvKYlo2CPhVPkJlW" } } ~~~ Step 4: Server processes payment and returns resource

Decoded receipt: ~~~ json { "method": "stripe", "reference": "pi_1N4Zv32eZvKYlo2CPhVPkJlW", "status": "success", "timestamp": "2025-01-15T12:04:32Z" } ~~~

Acknowledgements The authors thank the Tempo community for their feedback on this specification.