Ucp Payment Handlers

---
name: ucp-payment-handlers
description: >
  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.
---

# UCP Payment Handlers

## Before writing code

**Fetch live docs**:
- Google Pay handler: https://developers.google.com/merchant/ucp/guides/google-pay-payment-handler
- Shop Pay handler: Web-search `site:shopify.dev UCP Shop Pay payment handler`
- Payment architecture: https://ucp.dev/specification/overview/ (payment section)
- Reference types: https://ucp.dev/specification/reference/ (credential and instrument schemas)

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

1. **Digital Wallet** (Google Pay, Shop Pay): Platform acquires encrypted tokens from the wallet provider's API, sends to Business in `complete_checkout`.
2. **Direct Tokenization**: Platform calls PSP endpoint directly with Business's public key, gets network tokens.
3. **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:**
1. Configure your PSP (Stripe, Adyen, etc.) and get merchant credentials
2. Build payment handler config for your discovery profile — fetch the exact format from the live handler spec
3. On `complete_checkout`, extract the credential and forward it to your PSP for authorization
4. Map PSP responses back to UCP checkout status (completed, or error with messages)

**Platform side:**
1. Read `payment.handlers` from the checkout response
2. Use the handler's `config` to initialize the payment provider SDK (e.g., Google Pay JS API)
3. Acquire a payment credential from the user
4. Send it in the `complete_checkout` call

Always verify the exact handler config schema from the live spec — payment handler configurations change frequently.