acp-payment-handlers

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