UCP Payment Handlers
Before writing code
Fetch live docs:
Conceptual Architecture
Trust Triangle
Business <——> PSP <——> Credential Provider
- Credential Provider (Google Pay, Shop Pay): Issues encrypted payment tokens to the Platform
- PSP (Stripe, Adyen, etc.): Decrypts tokens, authorizes with card networks, settles funds
- Business: Configures which handlers/PSPs it accepts; receives credentials from Platform, forwards to PSP
Critical security rule: Credentials flow Platform → Business ONLY. Business MUST NEVER echo credentials back to the Platform.
Payment Handler Concept
A payment handler is a specification, not an entity. It defines:
id: Unique identifier for this payment handler instance
name: Reverse-domain identifier (e.g., com.google.pay, com.shopify.shop_pay)
version: Date-based version
spec: URI to the handler specification
config: Handler-specific configuration (merchant ID, accepted card networks, tokenization params)
config_schema: JSON Schema defining the structure of the config object for this handler
instrument_schemas: Schemas defining the shape of payment instruments this handler produces
Handlers are declared in the Business's discovery profile and echoed in checkout responses.
Three Payment Processing Scenarios
- Digital Wallet (Google Pay, Shop Pay): Platform acquires encrypted tokens from the wallet provider's API, sends to Business in
complete_checkout.
- Direct Tokenization: Platform calls PSP endpoint directly with Business's public key, gets network tokens.
- Autonomous Agent (AP2): Agent generates cryptographically-signed mandates proving user authorization — no human interaction needed. See the
ucp-ap2-mandates skill.
Credential Flow in Complete Checkout
When calling complete:
payment_data.instrument: Describes the payment method (type, brand, last digits, billing address)
payment_data.credential: The actual token/cryptogram (encrypted, handler-specific)
Implementation Guidance
Business side:
- Configure your PSP (Stripe, Adyen, etc.) and get merchant credentials
- Build payment handler config for your discovery profile — fetch the exact format from the live handler spec
- On
complete_checkout, extract the credential and forward it to your PSP for authorization
- Map PSP responses back to UCP checkout status (completed, or error with messages)
Platform side:
- Read
payment.handlers from the checkout response
- Use the handler's
config to initialize the payment provider SDK (e.g., Google Pay JS API)
- Acquire a payment credential from the user
- Send it in the
complete_checkout call
Always verify the exact handler config schema from the live spec — payment handler configurations change frequently.
1---2name: ucp-payment-handlers-23description: Implement UCP payment handlers — configure Google Pay, Shop Pay, or custom payment methods with tokenization, credential flow, and instrument schemas. Use when integrating payment processing into a UCP checkout.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/ucp-payment-handlers-27---89# UCP Payment Handlers1011## Before writing code1213**Fetch live docs**:14- Google Pay handler: https://developers.google.com/merchant/ucp/guides/google-pay-payment-handler15- Shop Pay handler: Web-search `site:shopify.dev UCP Shop Pay payment handler`16- Payment architecture: https://ucp.dev/latest/specification/overview/ (payment section)17- Reference types: https://ucp.dev/latest/specification/reference/ (credential and instrument schemas)1819## Conceptual Architecture2021### Trust Triangle2223```24Business <——> PSP <——> Credential Provider25```2627- **Credential Provider** (Google Pay, Shop Pay): Issues encrypted payment tokens to the Platform28- **PSP** (Stripe, Adyen, etc.): Decrypts tokens, authorizes with card networks, settles funds29- **Business**: Configures which handlers/PSPs it accepts; receives credentials from Platform, forwards to PSP3031**Critical security rule**: Credentials flow Platform → Business ONLY. Business MUST NEVER echo credentials back to the Platform.3233### Payment Handler Concept3435A payment handler is a **specification**, not an entity. It defines:36- `id`: Unique identifier for this payment handler instance37- `name`: Reverse-domain identifier (e.g., `com.google.pay`, `com.shopify.shop_pay`)38- `version`: Date-based version39- `spec`: URI to the handler specification40- `config`: Handler-specific configuration (merchant ID, accepted card networks, tokenization params)41- `config_schema`: JSON Schema defining the structure of the `config` object for this handler42- `instrument_schemas`: Schemas defining the shape of payment instruments this handler produces4344Handlers are declared in the Business's discovery profile and echoed in checkout responses.4546### Three Payment Processing Scenarios47481. **Digital Wallet** (Google Pay, Shop Pay): Platform acquires encrypted tokens from the wallet provider's API, sends to Business in `complete_checkout`.492. **Direct Tokenization**: Platform calls PSP endpoint directly with Business's public key, gets network tokens.503. **Autonomous Agent (AP2)**: Agent generates cryptographically-signed mandates proving user authorization — no human interaction needed. See the `ucp-ap2-mandates` skill.5152### Credential Flow in Complete Checkout5354When calling complete:55- `payment_data.instrument`: Describes the payment method (type, brand, last digits, billing address)56- `payment_data.credential`: The actual token/cryptogram (encrypted, handler-specific)5758### Implementation Guidance5960**Business side:**611. Configure your PSP (Stripe, Adyen, etc.) and get merchant credentials622. Build payment handler config for your discovery profile — fetch the exact format from the live handler spec633. On `complete_checkout`, extract the credential and forward it to your PSP for authorization644. Map PSP responses back to UCP checkout status (completed, or error with messages)6566**Platform side:**671. Read `payment.handlers` from the checkout response682. Use the handler's `config` to initialize the payment provider SDK (e.g., Google Pay JS API)693. Acquire a payment credential from the user704. Send it in the `complete_checkout` call7172Always verify the exact handler config schema from the live spec — payment handler configurations change frequently.