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

Shared 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. See .
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: Shared 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 Shared 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. The server MAY include Stripe Connect settlement parameters as described in :

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.

Stripe Connect Settlement Servers that use Stripe Connect MAY apply Connect parameters when creating the Stripe PaymentIntent. These parameters are settlement policy inputs controlled by the server, not payment request fields that clients need in order to create an SPT. The following Stripe PaymentIntent create parameters are compatible with this specification: Stripe parameter Description Stripe-Account header or SDK stripeAccount option Connected account used as the Stripe account context for the request application_fee_amount Platform application fee amount in the smallest currency unit on_behalf_of Connected account used as the business of record transfer_data[destination] Connected account that receives transferred funds transfer_data[amount] Amount transferred to transfer_data[destination] transfer_group Reconciliation token linking related charges and transfers Servers SHOULD derive Connect settlement parameters from server-side merchant configuration, platform policy, order state, or equivalent trusted state. Servers MUST NOT include Connect settlement parameters in the MPP challenge.

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 usage limits constrain the currency, maximum amount, and expiration window granted to the seller, but those limits are derived from the challenge parameters the client accepts. 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)

Stripe Connect Parameter Integrity Servers that use Stripe Connect settlement parameters MUST validate those parameters before creating the PaymentIntent: Connected account identifiers, including stripeAccount, on_behalf_of, and transfer_data[destination], MUST refer to connected accounts that the server is authorized to use for the current request. transfer_data[destination] MUST be present when transfer_data is present. application_fee_amount, when present, MUST be a non-negative integer no greater than the PaymentIntent amount. transfer_data[amount], when present, MUST be a non-negative integer no greater than the PaymentIntent amount. transfer_group, when present, MUST be derived from an order, invoice, request, or similar reconciliation identifier and MUST NOT be treated as secret. Servers MUST NOT accept Connect settlement parameters from clients unless an explicit trust boundary authorizes that client to control settlement routing or platform fees.

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. Shared 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. Shared payment tokens 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.