Proposal: Add preferred_network Field to AP2 Mandates

[jackmoggach]

Proposal: Add preferred_network Field to AP2 Mandates

Context

In markets with dual-network debit cards (DNDCs) — e.g. Australia — merchants have the regulatory right to determine the preferred network (Merchant Choice Routing, also known as Least Cost Routing).

The current AP2 v0.1 schema for CartMandate and PaymentMandate supports declaring accepted_networks in method_data, but does not provide a way to express a merchant’s preference when multiple networks are available.

Problem

• Without an explicit preferred_network field:
  • Credential Providers (CPs) and Shopping Agents could default to scheme tokens, even when the merchant prefers the domestic rail.
  • In disputes, evidence would show “accepted networks,” but not the merchant’s stated preference.
  • Liability for mis-routed transactions becomes ambiguous.

This gap creates risk in markets like Australia, where merchant routing preference is a regulatory and commercial requirement.

Proposed Change

Extend the AP2 schema for CartMandate and PaymentMandate to include a preferred_network field (and optionally fallback_rules) under payment_request.method_data.

Example — CartMandate:

{
  "ap2.mandates.CartMandate": {
    "contents": {
      "id": "cart_A_001",
      "items": [ ... ],
      "total": { "currency": "AUD", "value": 19.50 },
      "payment_request": {
        "method_data": [
          {
            "supported_methods": "CARD",
            "data": {
              "accepted_networks": ["EFTPOS","VISA"],
              "preferred_network": "EFTPOS",
              "fallback_rules": { "allow_scheme_fallback": true }
            }
          }
        ]
      }
    },
    "merchant_signature": "sig_merchantA"
  }
}

Example — PaymentMandate:

{
  "ap2.mandates.PaymentMandate": {
    "payment_details": {
      "cart_mandate": "hash(cart_A_001)",
      "payment_request_id": "order_A_001",
      "payment_method": {
        "supported_methods": "CARD",
        "data": {
          "network": "EFTPOS",   // aligned with merchant preference
          "token_ref": "tok:eftpos:wxyz"
        }
      },
      "amount": { "currency": "AUD", "value": 19.50 },
      "ai_presence": "HNP"
    },
    "agent_signature": "sig_shopping_agent"
  }
}

Benefits

• Merchant routing rights respected in DNDC markets (compliance with LCR rules).
• Clearer liability: if a CP/agent submits a token inconsistent with merchant preference, liability can be assigned based on the mandate evidence.
• Interoperability: standardises how preference is expressed globally, without bespoke network/market APIs.

Request

We propose adding preferred_network (and optional fallback_rules) to the AP2 mandate schema.
Would the maintainers and community support including this change in AP2 v1.x (with HNP support and multi-merchant topologies), given its regulatory significance in several markets?

[srotzin]

The domestic rail preference problem is real. We default to Base L2 USDC across the network — single rail, no preference negotiation needed at the agent layer. For enterprise agents that need domestic settlement the preferred_network field is the right escape hatch. The dispute evidence issue goes away if settlement is on-chain and auditable by default.

[chopmob-cloud]

This field is already implemented and running in production, which may be useful evidence for the proposal. The live AlgoVoi AP2/x402 agent card accepts a preferred_network on checkout creation and routes settlement accordingly across 8 chains (Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, ARC). The schema addition is not theoretical; an interoperable implementation already treats merchant network preference as a first-class input.

On the dispute-evidence point, which is the strongest part of the proposal: the gap closes cleanly if the chosen network is bound into a signed receipt at execution. In the AlgoVoi deployment each settlement carries a signed compliance receipt (EdDSA/Ed25519 JWS over JCS-canonical RFC 8785 bytes) that records the action and the rail it executed on. That turns "merchant stated a preference" into a non-repudiable artifact a dispute process can verify offline, rather than inferring intent from an accepted_networks list after the fact.

One suggestion: keep preferred_network advisory at the mandate layer as proposed, and recommend that conformant implementations record the network actually used in whatever receipt or evidence object they emit. Preference plus proof-of-routing is what makes the liability story hold up.

AlgoVoi (chopmob-cloud) -- docs.algovoi.co.uk/protocols/ap2