---
name: acp-payment-handlers
description: >
  Implement ACP payment handlers — pluggable payment method specifications
  including tokenized cards, seller-backed methods (gift cards, points, store
  credit), and handler negotiation. Use when adding payment methods or building
  custom payment handler support.
---

# ACP Payment Handlers

## Before writing code

**Fetch live docs**:
1. Web-search `site:github.com agentic-commerce-protocol rfcs payment_handlers` for the payment handlers RFC
2. Web-search `site:github.com agentic-commerce-protocol rfcs seller_backed` for seller-backed payment handler RFC
3. Fetch `https://developers.openai.com/commerce/specs/payment/` for payment data structures
4. Web-search `site:docs.stripe.com agentic-commerce payment handler` for Stripe's handler implementation

## Conceptual Architecture

### What Payment Handlers Are

Payment handlers are **pluggable specifications** that define how a particular payment method works within ACP. Each PSP or merchant publishes handler specs, and agents/merchants negotiate which handlers they mutually support.

This inverts the traditional integration model — instead of hardcoding payment methods into the protocol, handlers are discoverable and composable.

### Handler Identification

Each handler has a reverse-DNS name and version:
- `dev.acp.tokenized.card` — Tokenized credit/debit cards (Stripe SPT)
- `dev.acp.seller_backed.saved_card` — Pre-stored cards on merchant
- `dev.acp.seller_backed.gift_card` — Gift cards with number/PIN
- `dev.acp.seller_backed.points` — Loyalty/rewards points
- `dev.acp.seller_backed.store_credit` — Account balance/store credit

### Handler Structure

Each payment handler spec defines:
- **`id`** — Unique instance identifier within the session
- **`name`** — Specification name in reverse-DNS format (e.g., `dev.acp.tokenized.card`)
- **`version`** — Spec version
- **`spec`** — URL to the handler specification
- **`requires_delegate_payment`** — Whether the agent must call `/delegate_payment` (true for tokenized cards)
- **`requires_pci_compliance`** — Whether PCI DSS scope is affected
- **`psp`** — Which PSP processes this handler
- **`config_schema`** — JSON Schema for merchant configuration
- **`instrument_schemas`** — JSON Schema(s) for the payment instrument data the agent sends

### Tokenized Card Handler

The primary handler — uses Stripe's delegated payment:
1. Agent provisions SPT via Stripe
2. Agent sends SPT as the instrument credential in `complete`
3. Merchant charges via Stripe using the SPT
4. `requires_delegate_payment: true`

### Seller-Backed Handlers

These bypass the PSP — the merchant directly manages the payment:
- **Saved card** — Customer has a card on file with the merchant
- **Gift card** — Number + optional PIN
- **Points** — Loyalty program balance
- **Store credit** — Account balance
- `requires_delegate_payment: false`
- `requires_pci_compliance: false` (except saved cards)

### Handler Negotiation

During capability negotiation:
1. Agent advertises supported payment handlers in `capabilities.payment.handlers[]`
2. Merchant responds with handlers they accept
3. Intersection determines available payment methods for the session
4. Agent picks one and provides the appropriate instrument data

### Payment Data Structure

When completing a checkout, the agent provides:
- `handler_id` — Which handler is being used
- `instrument` — `type` + `credential` (shape defined by handler's instrument schema)
- Optional `billing_address`

### Best Practices

- Support multiple handlers to maximize conversion
- Advertise all accepted handlers in capability negotiation
- Validate instrument data against the handler's instrument schema
- Handle handler-specific errors (e.g., insufficient points, expired gift card)
- Log handler usage for payment method analytics

Fetch the payment handlers RFC and instrument schemas from the GitHub repo for exact field definitions before implementing.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/acp-agentic-commerce/skills/acp-payment-handlers/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/acp-agentic-commerce/skills/acp-payment-handlers/SKILL.md
Attribution basis: Source repository record

Fields of work: Marketing, Sales
Roles: Business Development, Customer Success Manager, Growth Marketer, Product Marketer, Sales Engineer
Specialties: API
Tools: Github, Stripe
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 7f98d133e63095a3ed98496ce2460ea4d3380a65981b5ccba7a5133fc4afb519