Card 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.
Status: Preview on mocks. Live credit card keys are Release-gated.
Card agent programs give an agent a card token bound to a person and to that agent, with spend controls. Dynamo accepts such a token as the funding of a root credit card budget, so the token's controls and the budget's own caps apply together.
Programs modelled
| Program | Modelled on an offline mock |
|---|---|
| Mastercard Agent Pay | agent-bound token records and Verifiable Intent (the person's constraints) |
| Visa Intelligent Commerce | credentials per purchase instruction with spend controls, and the Trusted Agent Protocol key directory |
The mock's paths are its own: there is no published Agent Pay API, and no live key directory is contacted.
The interface
The core speaks to a program's token service through four calls: verify a token, fetch credentials for one purchase, fetch an agent's public key, and read a token's current state. Token records, purchase credentials and token states are records signed by the program; the core checks each against one pinned signer address. The key directory answers the agent's public key, which the core uses to check the agent's own signature.
Behaviour
- Funding enters only as the funding of a root credit card budget, on
the existing credit card rail.
- The token's controls are intersected with the budget's mandate, and
the narrower wins: per-transaction maximum, validity window and recurrence. A budget cap above the token's total is refused, never clamped. This deployment's merchant must be on the token's merchant list.
- No card number is stored. A value shaped like a card number in a
request is refused (card_agent_card_number) and never echoed.
- Other named refusals include
card_agent_token_unusable,
card_agent_proof_invalid, card_agent_unavailable, card_agent_merchant_not_allowed and card_agent_cap_exceeds_token.
Routes
Only when the switch is on:
GET /owner/v1/card-agent-programs- the switch state and how each
program's controls map
POST /owner/v1/card-agent-programs/fundings- fund a root credit card
budget with an agent-bound token
GET /owner/v1/card-agent-programs/fundings/{id}- one funding
Switches
| Switch | Default | Notes |
|---|---|---|
CORE_CARD_AGENT_PROGRAMS | off | mock turns the programs on; needs the credit card mode |
CORE_CARD_AGENT_MOCK_URL | none | https, or http on loopback; a program's production host refuses to start |
CORE_CARD_AGENT_MOCK_API_KEY | none | a test credential only; a live or production credential refuses to start (card_agent_live_key) |
CORE_CARD_AGENT_SIGNER | none | the program's record signer address |
CORE_CARD_AGENT_MERCHANT | none | this deployment's merchant domain |
CORE_CARD_RAIL_MODE | test | live needs every safeguard and still stops at card_live_release_gated |
The credit card rail runs in Stripe TEST mode only. A live configuration needs a sealed key, signed webhooks, strict payee verification and a release acknowledgement, and even then the core refuses to start with card_live_release_gated.
Test suites
make test-card-agent-programs- off by default, live credentials
refused, both programs on mocks funding root credit card budgets on the Stripe TEST simulator, controls never wider than the mandate, no card number stored, tenants isolated.
make test-card-live-ready- each missing live safeguard refused by
name; a complete live configuration stops at the release gate.
Mocks today, partner access later
Both programs run on mocks with Stripe TEST. A program sandbox would need the program's published API and test credentials. Live use waits for the release gate.
Certification steps
- Both suites green.
- Every named
card_agent_refusal produced against the program's
answers.
card_agent_live_keyshown for a live credential and for a production
host.