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).
| Variable | Meaning |
|---|---|
CORE_CARD_AGENT_PROGRAMS | off (default) or mock |
CORE_CARD_AGENT_MOCK_URL | the mock's base URL (https, or http on loopback); never a program's production host |
CORE_CARD_AGENT_MOCK_API_KEY | a test credential, cap_test_<secret> |
CORE_CARD_AGENT_SIGNER | the pinned address that signs the programs' token records and the Verifiable Intent issuer layer |
CORE_CARD_AGENT_MERCHANT | this 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": {…}}}
- Mastercard Agent Pay: the agentic token reference and the Verifiable
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.
- Visa Intelligent Commerce:
instructionIdandtap, the agent's
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 control | Mandate 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 / budget | capTotal must be at or below it (refused, never clamped) |
| validity window, recurrence | validFrom / validUntil / perPeriod, the narrower wins |
| merchant allow-list | this 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
- Mastercard has published no Agent Pay token-service API as of 2026-10-08:
the mock's token-service paths are its own.
- Verifiable Intent (draft v0.1) is a layered SD-JWT format. The mock models
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).
- Visa's flow on the Visa Acceptance Platform includes passkey authentication
of the person and the Agentic Consumer Recognition Object; the mock models neither.
- Visa Intelligent Commerce Connect is a pilot: the mock models the
credential retrieval path through the Visa Acceptance Platform as described publicly; the Trusted Agent Protocol key directory is the mock's.
- No live network is reachable: the mocks are offline, the card rail is
Stripe TEST.
Errors: the card_agent_* codes in all error codes.