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?