Wallet

Visa Intelligent Commerce

How Wallet turns an approved authorization into a real Visa network credential.

Visa Intelligent Commerce (VIC) is the rail behind an authorization created with mode: "network". Wallet enrolls your card as a Visa network token, binds the authorization to a Visa purchase instruction you confirm with a payment passkey, and then hands the agent a credential that only works inside that instruction.

What Wallet does on your behalf

1
Network token: your card is enrolled with Visa Token Service (VTS), which returns a provisioned token. Wallet stores the token reference and the last four digits — never the card number or CVV2.
2
Device binding and issuer step-up: Visa asks your issuer to bind this device. When the issuer challenges, you complete a one-time code by SMS or email, or an out-of-band approval in your banking app.
3
Visa Payment Passkey: you register a passkey for the token on this device. Touch ID, Face ID, or your device PIN replaces every later password.
4
Purchase-instruction authentication: when you approve a network authorization, Wallet creates a Visa purchase instruction carrying its limits, and you confirm it with the passkey. Nothing can be issued before you do.
5
Credentials for the instruction: the agent asks for a credential per purchase. Visa returns a token number plus dynamic data, bound to the instruction's amount, merchant, and expiry.
6
Confirmations: the agent reports each outcome back to Visa. Unreported outcomes block cancellation.

The instruction carries the same terms you saw on the approval page: a decline threshold (the per-purchase maximum), an effective until date, a description, and a preferred merchant when the authorization allows exactly one. Your authorization page lists every instruction, its state, the credentials issued against it, and the confirmations Visa received.

DAVV and TAVV

Each credential carries dynamic data that is useless outside its purchase. Which kind you get is decided by Visa, and Wallet reports the real one rather than the one it asked for.

`DAVV`	A dynamic card security code. It arrives in the credential's security_code field with kind DYNAMIC_SECURITY_CODE and its own expiry, usually minutes.
`TAVV`	A token authentication verification value — a cryptogram. It arrives in the separate cryptogram field with an ECI, never in a CVV field.

Never move a cryptogram into a CVV field

A TAVV cryptogram is not a security code. Sending it as one makes the payment fail and can look like credential abuse. Read credential.security_code and cryptogram as the mutually exclusive fields they are.

Cancelling and revoking

You can cancel a pending, authenticated, or active purchase instruction from the authorization page at any time before the agent completes it. Revoking the authorization blocks new credentials immediately; the Visa instruction is cancelled once the outcomes of any credential already retrieved are reported.

Visa refuses a cancellation with CONFIRMATION_REQUIRED while a retrieved credential has no confirmation. Ask the agent to report the outcome, then cancel.

MCP tools

The Visa tools need the wallet:credentials scope in addition to the existing ones.

`create_authorization`	Takes an optional mode of "mock" (default) or "network" and an optional instrument_id. Network mode needs a Visa-ready card and answers with mode, authentication_required, and an approval_url.
`issue_purchase_credential`	Issues a Visa credential for an authenticated instruction. The first call creates credentials for the instruction; later calls retrieve more within the same terms.
`get_credential_request`	Returns the safe record of one credential request. It never replays the credential values.
`report_credential_outcome`	Reports approved, declined, error, or cancelled back to Visa, with the merchant order id and amount.

issue_purchase_credential takes the authorization, the merchant, the amount, the cart, and an idempotency key:

{
  "authorization_id": "mnd_example",
  "merchant": {"name": "Example", "url": "https://example.test/checkout", "country": "US"},
  "amount_minor": 18420,
  "currency": "USD",
  "cart": {
    "summary": "Example item",
    "hash": "sha256:cart-example",
    "items": [{"name": "Example item", "quantity": 1, "unit_amount_minor": 18420}]
  },
  "shipping_required": true,
  "idempotency_key": "issue-example-1"
}

An issued credential comes back in this shape:

{
  "status": "issued",
  "credential_request_id": "vcr_example",
  "grant_id": "grt_example",
  "instruction_id": "vins_example",
  "visa_instruction_id": "example",
  "format": "CARD_FORM",
  "network": "VISA",
  "credential": {
    "brand": "VISA",
    "holder_name": "ADA LOVELACE",
    "number": "<network token>",
    "expiration_month": "12",
    "expiration_year": "2031",
    "security_code": {
      "value": "<DAVV>",
      "kind": "DYNAMIC_SECURITY_CODE",
      "scheme_type": "DAVV",
      "expires_at": "2026-09-17T15:20:00Z"
    },
    "display": {"last4": "2345", "label": "Visa ending 2345"}
  },
  "cryptogram": null,
  "user_agent_authorization": "<opaque>",
  "amount_minor": 18420,
  "currency": "USD",
  "merchant": {"url": "https://example.test/checkout"},
  "next_tool": "report_credential_outcome",
  "next_tool_args": {"credential_request_id": "vcr_example"}
}

After the purchase settles, the agent must close the loop:

{
  "credential_request_id": "vcr_example",
  "outcome": "approved",
  "merchant_order_id": "ord_example",
  "amount_minor": 18420,
  "currency": "USD",
  "tracking": {"id": "1Z999", "carrier": "UPS", "method": "ground"},
  "idempotency_key": "outcome-example-1"
}

The reply is {"status":"recorded","confirmation_id":"vcf_…","visa_status":"…","instruction_status":"…"}.

Refusal codes

`AUTHENTICATION_REQUIRED`	The owner has not confirmed the instruction with a passkey, or the 7-day authentication window lapsed. The refusal carries the approval_url to send them to.
`INSTRUMENT_NOT_NETWORK_READY`	The card has no ready Visa enrollment. Call get_payment_setup_link and let the owner finish enrollment.
`INSTRUCTION_NOT_ACTIVE`	The instruction was cancelled, completed, or expired. A new authorization is needed.
`MANDATE_EXCEEDED`	The amount is above the decline threshold, the merchant is not the preferred one, or the effective-until date has passed.
`CREDENTIAL_LIMIT_REACHED`	The instruction has issued its maximum number of credentials.
`CONFIRMATION_REQUIRED`	A retrieved credential has no reported outcome yet, so the instruction cannot be cancelled.
`VISA_UNAVAILABLE`	Visa did not answer. This one is retryable.

An agent must never retry an unchanged refusal. Fix the request, or ask the owner for a new authorization.

Sandbox and simulator

The wallet service picks its Visa rail with VISA_MODE.

`simulator`	The default. An in-process Visa that answers with the same shapes as the sandbox: any Luhn-valid PAN starting with 4 enrolls, the step-up code is VISA_SIMULATOR_OTP, and passkeys are simulated. No network calls leave the machine.
`sandbox`	Visa's sandbox at VISA_BASE_URL, reached with your VDC project credentials over two-way TLS (or an X-Pay-Token) and the VTS keys.
`certification`	The certification endpoints, with the same credential set.

The wallet Settings page reports the live mode, whether mTLS, message-level encryption, and VTS field-level encryption are active, and whether Visa answers a ping.

What Wallet never stores

Your card number and CVV2 are sent to Visa and never persisted or logged.
Credential values, dynamic security codes, and cryptograms are handed to the agent once and never replayed by a read tool.
The activity timeline and the authorization pages show token last four digits, amounts, merchants, and states — never a full number.
Visa data sharing is a separate, explicit consent, recorded with its version and timestamp.