Card agent programs

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

Fund a root credit card budget with an agent-bound card token from Mastercard Agent Pay or Visa Intelligent Commerce. The token's own spend controls narrow the budget's mandate: where the token is stricter, the mandate becomes stricter; where the mandate is stricter, it stays as it is.

Status: Preview. Off by default, test mode only. CORE_CARD_AGENT_PROGRAMS=mock turns it on against offline mocks of both programs. It needs the credit card mode (Stripe TEST): without it the core refuses to boot (card_agent_config_invalid). With the switch off, none of these routes exists. A live or production program credential (cap_live_…, cap_prod_…) in any variable, or a program's production host, refuses to boot (card_agent_live_key).

VariableMeaning
CORE_CARD_AGENT_PROGRAMSoff (default) or mock
CORE_CARD_AGENT_MOCK_URLthe mock's base URL (https, or http on loopback); never a program's production host
CORE_CARD_AGENT_MOCK_API_KEYa test credential, cap_test_<secret>
CORE_CARD_AGENT_SIGNERthe pinned address that signs the programs' token records and the Verifiable Intent issuer layer
CORE_CARD_AGENT_MERCHANTthis deployment's merchant domain as registered with the programs

Setting any of the other variables while the switch is off refuses boot. GET /owner/v1/card-agent-programs reports the switch state, the merchant, the signer and how each program's controls map.

Fund a budget

POST /owner/v1/card-agent-programs/fundings
Dynamo-Version: 1.8.0
{"program": "mastercard_agent_pay", "idempotencyKey": "<UUID v4>", "agentId": "…",
 "owner": "0x…", "capTotal": "8000000", "mandate": {"categories": ["research"], "maxDepth": 2},
 "tokenRef": "mcat_…", "intent": {"l1": {…}, "l2": {…}}}

Intent chain. Layer 1, signed by the credential provider, binds the person's key; it must be the budget's root funder (owner). Layer 2, signed by that key, names the agent, this merchant and the constraints the agent was told to keep.

Trusted Agent Protocol signature over this deployment's merchant domain and the funding path. The instruction's credentials are fetched per funding.

The budget is an ordinary root credit card budget: one card authorization for the whole cap, naming the token's processor payment-method reference. Captures, payouts and refunds use the card rail's existing paths. The answer carries the narrowed mandate.

How the controls narrow the mandate

Token controlMandate field
per-transaction amount (Mastercard amount_range.max, Visa decline threshold)perTransactionMax, the lower wins; one authorization funds the cap, so it also bounds capTotal
amount limit / budgetcapTotal must be at or below it (refused, never clamped)
validity window, recurrencevalidFrom / validUntil / perPeriod, the narrower wins
merchant allow-listthis deployment's merchant must be named, else refused

Card numbers

None is ever stored. A request carrying a card number answers 400 card_agent_card_number, never echoed; only the programs' token references and the processor's payment-method reference are kept.

Named limits

the mock's token-service paths are its own.

its layer 1 (credential provider binds the person's key) and layer 2 (the person's constraints) as signed JSON records, not SD-JWT with selective disclosure, and does not model layer 3 (the agent's per-purchase payment and checkout mandates in autonomous mode).

of the person and the Agentic Consumer Recognition Object; the mock models neither.

credential retrieval path through the Visa Acceptance Platform as described publicly; the Trusted Agent Protocol key directory is the mock's.

Stripe TEST.

Errors: the card_agent_* codes in all error codes.