# Stripe Payments handler for UCP

Use Stripe payment handlers for card, Apple Pay, and Google Pay in UCP checkout.

Use the `com.stripe.payments` handler for card and Apple Pay payments in a [Universal Commerce Protocol](https://ucp.dev) (UCP) checkout. Google Pay uses the separate `com.google.pay` handler. This page shows what sellers advertise and receive, and describes checkout on Stripe-hosted endpoints to agents.

Link can appear in the seller’s `com.stripe.payments` configuration, but this handler doesn’t support Link payment completion.

## Key concepts 

These UCP terms describe the roles and payment objects used throughout the guide:

| Term | Meaning |
| --- | --- |
| Buyer | The customer who selects and authorizes the payment. |
| Platform | The agent or application acting for the buyer and sending checkout requests. |
| Business | The seller offering the checkout and accepting the payment. |
| UCP profile | The discovery resource that advertises the seller’s UCP services, payment handlers, and available instruments. |
| Checkout response | The current checkout state, including the handler configuration and available instruments for that checkout. |
| Payment handler | The contract for how an agent obtains and submits a payment credential the seller accepts. |
| Available instrument | The payment method the seller offers in its profile or checkout response. |
| Payment instrument | The selected method and credential the agent sends in Complete Checkout. |
| Credential | The token or other payment data used to process the selected method. |
| Complete Checkout | The UCP operation that the agent uses to submit the selected payment instrument. |

## How it works 

The following card flow shows a checkout served by the seller. The agent sends a shared payment token (SPT) in the Complete Checkout request, and the seller charges it before returning the checkout. Apple Pay and Google Pay skip card tokenization, and Stripe-hosted checkout processes payment for the seller.

An agent creates a UCP checkout with a seller, tokenizes card details with Stripe, and sends the token to the seller, who charges it. (See full diagram at https://docs.stripe.com/agentic-commerce/protocols/ucp/stripe-payments-handler)

```text
[Agent] -- Create checkout --> [Seller]
[Seller] -- Return checkout with card available through com.stripe.payments --> [Agent]
[Agent] -- Present card collection --> [Buyer]
[Buyer] -- Enter card details and approve --> [Agent]
[Agent] -- Tokenize card details with checkout context --> [Stripe]
[Stripe] -- Return scoped payment token --> [Agent]
[Agent] -- Complete checkout with returned token --> [Seller]
[Seller] -- Process payment using token --> [Stripe]
[Stripe] -- Return payment result --> [Seller]
[Seller] -- Return completed checkout --> [Agent]
[Agent] -- Show checkout result --> [Buyer]
```

## For sellers 

Your UCP profile tells agents which payment methods they can use. The Complete Checkout request carries the instrument they select.

### Review your payment handlers 

Your Stripe-hosted UCP profile is at `https://ucp.stripe.com/.well-known/ucp/{BUSINESS_PROFILE_ID}`. To serve checkout requests from your own endpoint, publish the `com.stripe.payments` handler in your UCP profile with your Stripe profile ID, environment, and available instruments. Publish `com.google.pay` separately if you accept Google Pay.

### Supported payment methods 

Each payment method has a handler ID, instrument type, and credential type:

| Flow | Handler ID | Instrument | Credential | Support |
| --- | --- | --- | --- | --- |
| Card | `stripe_payments` | `card` | `stripe_payment_token` | Tokenize card details to obtain an SPT, then submit the returned credential. |
| Apple Pay | `stripe_payments` | `apple_pay` | `pk_payment_token` | Submit a serialized Apple Pay token directly to completion. |
| Google Pay (separate handler) | `stripe-handler` | `card` | `PAYMENT_GATEWAY` | Use the seller’s `com.google.pay` configuration and submit the Google Pay token directly to completion. |

### Business profile example 

This live-mode profile advertises cards, Apple Pay, and Google Pay. Google Pay’s `allowed_payment_methods` lists the accepted card networks and authorization methods. Replace the example IDs and keys with your own values.

```json
{
  "ucp": {
    "version": "2026-01-23",
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "stripe-handler",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "PRODUCTION",
            "merchant_info": {
              "merchant_name": "Example Store",
              "merchant_id": "<GOOGLE_PAY_MERCHANT_ID>"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                  "allowed_card_networks": ["VISA", "MASTERCARD", "AMEX", "DISCOVER", "JCB"],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "stripe",
                    "stripe:publishableKey": "pk_live_example",
                    "stripe:version": "2018-10-31"
                  }
                }
              }
            ]
          }
        }
      ],
      "com.stripe.payments": [
        {
          "id": "stripe_payments",
          "version": "2026-06-25",
          "spec": "https://docs.stripe.com/agentic-commerce/protocols/ucp/stripe-payments-handler",
          "schema": "https://ucp.stripe.com/payments/2026-06-25/schema.json",
          "available_instruments": [
            {
              "type": "card",
              "constraints": {
                "properties": {
                  "brand": {
                    "enum": ["visa", "mastercard", "amex", "discover"]
                  }
                }
              }
            },
            {
              "type": "link",
              "config": {
                "business_profile": "profile_seller_xyz"
              }
            },
            {
              "type": "apple_pay",
              "config": {
                "apple_pay_merchant_identifiers": ["merchant.com.example.store"]
              }
            }
          ],
          "config": {
            "environment": "livemode",
            "business_profile": "profile_seller_xyz"
          }
        }
      ]
    }
  }
}
```

### Handler configuration 

The seller’s `com.stripe.payments` configuration contains these properties:

| Property | Type | Description |
| --- | --- | --- |
| `environment` | string | The seller’s mode: `testmode` or `livemode`. |
| `business_profile` | string | The seller’s Stripe profile ID (`profile_*`). |

Each available instrument can also provide configuration:

| Instrument | Property | Description |
| --- | --- | --- |
| `card` | `constraints.properties.brand.enum` | The card brands the seller accepts. |
| `apple_pay` | `config.apple_pay_merchant_identifiers` | The merchant identifiers available for Apple Pay. |
| `link` | `config.business_profile` | The seller profile used for Link credential acquisition. |

### Receive the payment instrument 

The agent sends the selected instrument in the Complete Checkout request. For a card payment, `credential.token` contains the SPT:

```json
{
  "payment": {
    "instruments": [
      {
        "id": "instr_1",
        "handler_id": "stripe_payments",
        "type": "card",
        "selected": true,
        "credential": {
          "type": "stripe_payment_token",
          "token": "spt_123"
        }
      }
    ]
  }
}
```

For Apple Pay, the instrument uses `type: "apple_pay"` and a `pk_payment_token` credential. Google Pay uses the `com.google.pay` handler and a `PAYMENT_GATEWAY` credential.

### Payment instrument properties 

The completion request identifies the selected instrument and its credential:

| Property | Type | Description |
| --- | --- | --- |
| `id` | string | The identifier for this instrument in the checkout. |
| `handler_id` | string | The handler ID from seller discovery, such as `stripe_payments`. |
| `type` | string | `card` for an SPT or Google Pay token, or `apple_pay` for an Apple Pay token. |
| `selected` | boolean | `true` for the instrument used to complete the checkout. |
| `display` | object | Optional card details, such as brand and last four digits, shown to the buyer. |
| `credential.type` | string | `stripe_payment_token` for a card SPT, `pk_payment_token` for Apple Pay, or `PAYMENT_GATEWAY` for Google Pay. |
| `credential.token` | string | The SPT or wallet token. |

### Charge a card token 

To charge a card SPT received in a Complete Checkout request, create and confirm a PaymentIntent using the SPT as `payment_method_data[shared_payment_granted_token]`. Use the checkout total for the amount. This server-side request uses a [restricted API key](https://docs.stripe.com/keys/restricted-api-keys.md) with PaymentIntents write permission:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d amount=10000 \
  -d currency=usd \
  -d "payment_method_data[shared_payment_granted_token]=spt_123" \
  -d confirm=true
```

If the payment succeeds, complete the checkout. For the full seller flow, see [Use your own checkout](https://docs.stripe.com/agentic-commerce/sellers/use-cases/retail/ucp.md). Stripe handles the payment step for Stripe-hosted checkout.

## For agents 

Use the seller’s profile to find its payment handlers and available instruments. After creating a checkout, use the handler configuration returned with that checkout to complete the payment.

### Set up your agent 

Enable your agent integration. The examples use live mode, so your agent and seller profiles both need to be in live mode.

Set `STRIPE_AGENT_API_KEY` to your agent’s live mode secret API key on your server.

### Confirm an orchestrated commerce agreement 

Before you transact with a seller, confirm an [orchestrated commerce agreement (OCA)](https://docs.stripe.com/agentic-commerce/agents/embedded.md#manage-seller-relationships). The seller initiates the agreement, and you approve it in the Dashboard.

### Discover the seller 

Read the seller’s [UCP profile](https://docs.stripe.com/agentic-commerce/protocols/ucp/stripe-payments-handler.md#business-profile-example) before creating a checkout. It lists the handler IDs and available instruments. Use the handler configuration in the checkout response for the payment you collect. For card tokenization, send the checkout handler’s `config.business_profile` as `identity.access_token`. The platform handler’s `config` is optional; if present, it contains `environment` and can contain `business_profile`.

### Tokenize card details 

Exchange card details for an SPT at `POST https://commerce.stripe.com/api/ucp/tokenize`. Call from your server with the agent’s Stripe secret API key as the bearer token.

#### Request 

Use the checkout’s `id` for `binding.id`, and the checkout handler’s seller profile for `identity.access_token`. Align `usage_limits.max_amount` and `currency` with the checkout total and currency. In this example, `10000` minor units represents 100 USD.

```bash
curl https://commerce.stripe.com/api/ucp/tokenize \
  -X POST \
  -H "Authorization: Bearer ${STRIPE_AGENT_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "credential": {
      "type": "pan",
      "number": "<CARD_NUMBER>",
      "expiry_month": 12,
      "expiry_year": 2034
    },
    "binding": {
      "type": "dev.ucp.shopping.checkout",
      "id": "rcs_123"
    },
    "identity": {
      "access_token": "profile_seller_xyz"
    },
    "usage_limits": {
      "max_amount": 10000,
      "currency": "usd"
    }
  }'
```

Replace the example IDs and card details with values from your checkout.

The tokenization request uses these properties:

| Property | Type | Description |
| --- | --- | --- |
| `credential.type` | string | `pan` for card details. |
| `credential.number` | string | The card number |
| `credential.expiry_month` | integer | The card expiration month |
| `credential.expiry_year` | integer | The card expiration year |
| `credential.cvc` | string | The card verification code, if collected |
| `binding.type` | string | `dev.ucp.shopping.checkout` for a UCP checkout |
| `binding.id` | string | The checkout ID |
| `identity.access_token` | string | The Seller’s `business_profile` from discovery |
| `usage_limits.max_amount` | integer | The maximum amount in the currency’s smallest unit |
| `usage_limits.currency` | string | The three-letter currency code |

#### Response 

```json
{
  "type": "stripe_payment_token",
  "token": "spt_123"
}
```

### Complete checkout 

Complete a checkout after it reaches `ready_for_complete` and has a buyer email. Send one selected [payment instrument](https://docs.stripe.com/agentic-commerce/protocols/ucp/stripe-payments-handler.md#payment-instrument-fields) with the handler ID from seller discovery.

#### Complete with a card 

In the URL, use the seller profile and checkout ID from your integration. Replace `spt_123` with the token returned by tokenization:

```bash
curl https://commerce.stripe.com/api/ucp/profile_seller_xyz/checkout-sessions/rcs_123/complete \
  -X POST \
  -H "Authorization: Bearer ${STRIPE_AGENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -H 'UCP-Agent: profile="https://agent.example/profile"' \
  --data-binary '{
    "payment": {
      "instruments": [
        {
          "id": "instr_1",
          "handler_id": "stripe_payments",
          "type": "card",
          "selected": true,
          "credential": {
            "type": "stripe_payment_token",
            "token": "spt_123"
          }
        }
      ]
    }
  }'
```

### Complete with a wallet 

Apple Pay and Google Pay provide tokens directly, without a PAN tokenize request.

#### Apple Pay 

Use an eligible seller merchant identifier from seller discovery to get an Apple Pay token through your wallet integration. Pass the serialized token as `credential.token` with the `pk_payment_token` credential type. Use the completion URL and server-side authentication from the card example:

```json
{
  "payment": {
    "instruments": [
      {
        "id": "instr_1",
        "handler_id": "stripe_payments",
        "type": "apple_pay",
        "selected": true,
        "credential": {
          "type": "pk_payment_token",
          "token": "<SERIALIZED_APPLE_PAY_TOKEN>"
        }
      }
    ]
  }
}
```

#### Google Pay 

Stripe-hosted checkout accepts Google Pay through the separate `com.google.pay` handler. Initialize the Google Pay SDK from the seller’s gateway configuration, then submit its token directly to completion using that handler’s ID. See the [Google Pay UCP payment handler guide](https://developers.google.com/pay/api/universal-commerce-protocol/google-pay-payment-handler) for the wallet integration:

```json
{
  "payment": {
    "instruments": [
      {
        "id": "instr_1",
        "handler_id": "stripe-handler",
        "type": "card",
        "selected": true,
        "credential": {
          "type": "PAYMENT_GATEWAY",
          "token": "<TOKEN_RETURNED_BY_GOOGLE_PAY>"
        },
        "billing_address": {
          "street_address": "123 Main Street",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94103",
          "address_country": "US",
          "phone_number": "+14155550123"
        }
      }
    ]
  }
}
```

### Error handling 

Tokenization errors come from the API. Checkout completion returns errors in `messages`.

#### Tokenize API errors 

If tokenization fails, check the seller profile in `identity.access_token`, the agent and seller modes, and the card credential type. The agent and seller also need a confirmed OCA.

#### Completion messages 

Use each message’s `code` and `path` to find what the checkout needs. For example, `missing_buyer_info` can point to `buyer.email`.

These checkout completion messages show how the agent can respond:

| Failure | Error code | Severity | Next step |
| --- | --- | --- | --- |
| Card declined | `payment_declined` | `recoverable` | Ask the buyer for another card. |
| The seller-owned payment failed | `payment_failed` | `recoverable` | Ask the buyer for another payment method. |
| Missing buyer information | `missing_buyer_info` | `recoverable` | Add the information identified by `path` before retrying completion. |

### Security 

Follow these security and token rules when collecting card details and submitting payment credentials:

| Topic | Guidance |
| --- | --- |
| HTTPS | Make API requests over HTTPS. |
| PCI DSS | Collect card details through a PCI-compliant integration. |
| Secret API key | Keep the agent’s secret API key on your server. |
| Seller identity and limits | Use the checkout handler’s `config.business_profile` as `identity.access_token`. Set `usage_limits.max_amount` and `usage_limits.currency` to the checkout total and currency. |
| Token lifecycle | If you omit `usage_limits.expires_at`, the SPT expires one hour after Stripe issues it. |
| No detokenization | Submit the returned SPT in Complete Checkout. Stripe processes it during payment, so your integration doesn’t need a detokenization step. |

## References 

These Stripe schemas use handler version `2026-06-25`:

| Contract | Schemas |
| --- | --- |
| Handler declarations | The [handler schema](https://ucp.stripe.com/payments/2026-06-25/schema.json), including the [business definition](https://ucp.stripe.com/payments/2026-06-25/schema.json#/$defs/com.stripe.payments/business_schema), [platform definition](https://ucp.stripe.com/payments/2026-06-25/schema.json#/$defs/com.stripe.payments/platform_schema), and [response definition](https://ucp.stripe.com/payments/2026-06-25/schema.json#/$defs/com.stripe.payments/response_schema). Existing flat definition aliases remain available. |
| Configuration | The [business config](https://ucp.stripe.com/payments/2026-06-25/business_config.json), [platform config](https://ucp.stripe.com/payments/2026-06-25/platform_config.json), and [checkout-handler response config](https://ucp.stripe.com/payments/2026-06-25/response_config.json). |
| Availability | The [business and response availability](https://ucp.stripe.com/payments/2026-06-25/available_instrument.json) and [platform availability](https://ucp.stripe.com/payments/2026-06-25/platform_available_instrument.json). |
| Instruments | The [instrument union](https://ucp.stripe.com/payments/2026-06-25/payment_instrument.json), [Card](https://ucp.stripe.com/payments/2026-06-25/card.json), [Apple Pay (`applepay.json`)](https://ucp.stripe.com/payments/2026-06-25/applepay.json), and [Link metadata](https://ucp.stripe.com/payments/2026-06-25/link.json). |
| Credentials | The [Stripe payment token](https://ucp.stripe.com/payments/2026-06-25/stripe_payment_token.json), [Apple Pay token](https://ucp.stripe.com/payments/2026-06-25/apple_pay_token.json), and [credential union](https://ucp.stripe.com/payments/2026-06-25/token_credential.json). |
| Tokenization | The [request](https://ucp.stripe.com/payments/2026-06-25/tokenize_request.json) and [response](https://ucp.stripe.com/payments/2026-06-25/tokenize_response.json). The response shares the Card credential schema. |

For the upstream payment contracts, see the [UCP payment guide (2026-08-25)](https://ucp.dev/2026-08-25/specification/payment/guide/) and [UCP tokenization guide (2026-08-25)](https://ucp.dev/2026-08-25/specification/payment/tokenization/).