← Articles

UCP Payment Instruments: First-Class Support for Payment Method Constraints

A proposal adds available_instruments to UCP payment handler configurations — enabling handlers to declare which payment methods they support and with what constraints. Essential infrastructure for installments, BNPL, and multi-payment orchestration.

The Problem

Today, UCP payment handlers can technically specify which payment instruments they accept, but it's done through an unstructured config blob. Each payment provider defines their own schema, leading to fragmentation:

// Provider A's approach
{
  "config": {
    "accepted_cards": ["visa", "mastercard"],
    "allow_apple_pay": true
  }
}

// Provider B's approach
{
  "config": {
    "payment_methods": {
      "cards": { "brands": ["visa", "mc", "amex"] },
      "wallets": ["applepay"]
    }
  }
}

This divergence creates problems for AI agents. An agent can't reliably determine which payment methods a checkout supports without understanding each provider's proprietary schema.

The Solution

The proposal introduces a standardized available_instruments array at the payment handler level:

{
  "payment_handler": {
    "id": "stripe-handler",
    "available_instruments": [
      {
        "type": "card",
        "constraints": {
          "brands": ["visa", "mastercard", "amex"]
        }
      },
      {
        "type": "digital_wallet",
        "constraints": {
          "providers": ["apple_pay", "google_pay"]
        }
      }
    ]
  }
}

Why This Matters for Agentic Commerce

The proposal explicitly calls out the future use case: payment terms and purchase options. Consider an "Affirm" style buy-now-pay-later flow:

1. Merchant offers 4-payment installment plan
2. Plan is only available for credit cards (not debit)
3. Plan is only available for orders over $50
4. AI agent needs to understand these constraints to present correct options to user

Without structured instrument constraints, this logic lives in ad-hoc provider configs. With available_instruments, it becomes queryable protocol-level information.

Technical Details

The PR introduces:

• Base schema: available_payment_instrument.json defines the structure all instrument types must follow
• Card-specific extension: card_payment_instrument.json adds card brand constraints
• Optional field: When available_instruments is absent, all instruments are considered available (backward compatible)
• Documentation updates: Schema authoring guide and payment handler guide updated with examples

The constraint pattern is extensible. Future instrument types (crypto, BNPL providers, regional payment methods) can define their own constraint schemas following the base pattern.

Implications

This change is foundational for several upcoming UCP features:

• Payment terms: "Pay in 4" requires knowing which instruments support installments
• Multi-payment orchestration: Split payments across multiple methods need constraint validation
• Regional payment methods: iDEAL (Netherlands), PIX (Brazil), UPI (India) have different constraints
• Dynamic checkout: AI agents can filter available options based on user's saved payment methods

The PR is currently open and under review. Given its non-breaking nature and clear use case, expect it to merge relatively quickly.