Private preview

Stripe Payments handler for UCP Private preview

Accept payments through UCP-compatible platforms using the Stripe unified payment handler.

Private preview

The com.stripe.payments handler is in private preview. To request access, contact your Stripe account team.

Use the com.stripe.payments handler to accept payments through Universal Commerce Protocol (UCP) compatible platforms. This handler provides a unified interface for all Stripe payment methods through credential tokenization.

In UCP terminology, platform refers to the agent or application acting on behalf of the consumer, business refers to the merchant or seller processing the payment.

How it works

The Stripe Payments handler enables credential acquisition and payment processing for UCP checkouts:

1. Discovery : The business advertises com. stripe. payments in its UCP profile at /. well-known/ucp , declaring supported instruments and their configuration.
2. Credential collection : The platform collects payment credentials from the consumer using the instrument’s configured credential provider.
3. Tokenization : The platform calls /tokenize with the raw credential. The handler returns an opaque, scoped token bound to the checkout and business.
4. Completion : The platform submits the token to the business’s checkout completion endpoint.

The business declares which instruments are available and whether each requires tokenization. The handler mediates between the platform and the business for all payment operations.

Supported instruments

The handler also accepts pre-existing tokens for instruments that don’t require tokenization.

Discovery

The business advertises com.stripe.payments in its UCP profile at /.well-known/ucp. The declaration includes all supported instruments, their constraints, and configuration the platform needs to render each payment method.

Business profile example

Handler configuration fields

Required:

Per-instrument configuration

Tokenize credentials

When an instrument declares "tokenization": "required", the platform must call /tokenize before completing payment. The endpoint accepts raw credentials and returns an opaque, scoped token bound to the checkout and business.

Endpoint: POST https://ucp.stripe.com/handlers/payments/tokenize

Authentication: Bearer token using the publishable_key from handler config.

Request

POST /tokenize
Content-Type: application/json
Authorization: Bearer pk_live_abc123

{
 "credential": {
 "type": "card",
 "card_number_type": "fpan",
 "number": "4242424242424242",
 "expiry_month": 12,
 "expiry_year": 2027,
 "cvc": "314"
 },
 "binding": {
 "checkout_id": "chk_abc123",
 "identity": {
 "access_token": "acct_merchant_xyz"
 }
 },
 "allowance": {
 "max_amount": 10000,
 "currency": "usd",
 "expires_at": "2027-01-15T14:35:00Z"
 }
}

Response

{
 "token": "tok_1abc2def3ghi",
 "type": "stripe_payment_token",
 "expires_at": "2027-01-15T14:35:00Z"
}

Request fields

Complete payment

After acquiring a token (either from /tokenize or from a wallet or provider UI), the platform submits it in the checkout completion request.

POST /checkout-sessions/{checkout_id}/complete
Content-Type: application/json
UCP-Agent: profile="https://agent.example/profile"

{
 "payment": {
 "instruments": [
 {
 "id": "instr_1",
 "handler_id": "stripe_payments",
 "type": "card",
 "selected": true,
 "display": {
 "brand": "visa",
 "last_digits": "4242",
 "expiry_month": 12,
 "expiry_year": 2027
 },
 "credential": {
 "type": "stripe_payment_token",
 "token": "tok_1abc2def3ghi",
 "expires_at": "2027-01-15T14:35:00Z"
 }
 }
 ]
 }
}

Payment instrument fields

Wallet flows

For wallet instruments ( link, google_pay, apple_pay), the platform renders the wallet provider’s UI using the configuration from discovery. The consumer authenticates within the wallet UI, and the platform receives a token directly. No /tokenize call is needed.

Link

1. Platform reads publishable _ key from the handler config
2. Platform initializes the Link UI with the publishable key
3. Consumer authenticates (passkey) and selects a saved payment method
4. Platform receives an opaque token
5. Platform submits the token in /complete

Link Agent Wallet

The Link Agent Wallet is a different acquisition flow for the same link instrument. Instead of rendering a Link UI, an AI agent acquires a payment credential through the link-cli. In this flow the agent does not read the publishable_key and does not initialize the Link UI. Every transaction requires the consumer to biometrically approve the spend in the Link app.

1. The agent creates a spend request using link-cli with the amount, business name, and (for on-Stripe businesses) credential _ type: shared _ payment _ token
2. The agent requests approval; the consumer approves biometrically in the Link app.
3. The agent retrieves the credential when it’s approved—a shared payment token (SPT) for on-Stripe businesses.
4. The platform submits the token in /complete using the existing link instrument ( credential. type: "stripe _ payment _ token" , with credential. token set to the acquired token).
5. The business charges the token with the shared payment token payment method.

The Link Agent Wallet reuses the existing link instrument and the generic stripe_payment_token credential, and doesn’t require a schema change. The business advertises com.stripe.payments with the link instrument in its /.well-known/ucp profile exactly as today (see Discovery). It doesn’t require a new instrument entry or config field. The agent-wallet path is enabled by the agent acquiring the token using the link-cli, and the SPT is what flows through for on-Stripe businesses.

For the full Spend Requests API and CLI usage, see stripe/link-cli.

Google Pay

1. Platform reads gateway and gateway _ merchant _ id from config
2. Platform initializes the Google Pay SDK
3. Consumer authenticates and selects a payment method
4. Platform receives a token
5. Platform submits the token in /complete

Apple Pay

1. Platform reads merchant _ identifier and supported _ networks from config
2. Platform initializes the Apple Pay session
3. Consumer authenticates (biometric) and selects a payment method
4. Platform receives a token
5. Platform submits the token in /complete

Consumer actions

Some payment methods require consumer interaction after submission (3D Secure challenges, the related setting approval). The handler returns a redirect action:

Platform flow:

1. Receive status: "requires _ action" with redirect _ url
2. Open the URL for the consumer (browser, webview, or iframe)
3. Consumer completes the interaction (3D Secure challenge, the related setting approval)
4. Platform re-submits /complete with the same checkout ID and instruments
5. Handler processes payment

Charge the token

The business uses the token from credential.token to create a Stripe PaymentIntent. The token is bound to the business’s account and can only be used once.

POST /v1/payment_intents
Content-Type: application/x-www-form-urlencoded

amount=10000&
currency=usd&
payment_method_data[type]=card&
payment_method_data[card][token]=tok_1abc2def3ghi&
confirm=true

Error handling

Security

References