Workflows

This section walks you through the available workflows for Visa Intelligent Commerce, from establishing a consumer-authorized purchase instruction to retrieving and confirming the payment credentials used to complete a purchase.

VIC's primary workflow goal is to establish a consumer-authorized purchase instruction, with one or more mandates, and draw tokenized payment credentials against it. Agents initiate every workflow; a successful outcome is a completed purchase using a Visa-issued credential.

This narrative walks through a typical agent-initiated purchase across every party involved (agent, Visa, issuer, and merchant) to complement the technical steps in API Reference by Workflow Step.

1. The consumer provides a purchase instruction to the agent, such as product, merchant, price ceiling, quantity, and validity window.
2. The agent may monitor inventory, price, or availability on the merchant site, but can only request payment credentials and complete checkout within the set instruction parameters.
3. When the agent identifies that the consumer's purchase instruction parameters are met, it confirms with the consumer and begins checkout.
4. The consumer authenticates the instruction, including through Visa Payment Passkey or other issuer-approved methods.
5. Visa enrolls the credential into the Visa Intelligent Commerce (VIC) platform, stores the purchase instruction with its parameters, and validates the transaction data against the purchase instruction criteria. If validation passes, VIC returns the tokenized payment credential and one-time cryptogram to the agent.
6. The agent submits the credential to the merchant checkout flow or a Payment Service Provider (PSP)-enabled flow.
7. The merchant or acquirer submits authorization through existing Visa rails.
8. Visa validates the token credential and confirms the authorization matches the transaction data the agent provided, performs risk and fraud checks, and sends the authorization message to the issuer.
9. The issuer processes the authorization under its existing controls.
10. If applicable, the agent sends post-purchase confirmation data to the Visa Intelligent Commerce platform, which Visa retains for use in the event of a dispute.

This journey is illustrative. Actual implementation flows, consumer experiences, data elements, and authentication mechanisms may vary depending on product evolution, participant implementation choices, issuer requirements, and regulatory considerations.

The API surface of Visa Intelligent Commerce centers on a single-call model: this call handles enrollment, instruction creation, and credential retrieval in one request, alongside calls to retrieve a subsequent credential, confirm transaction events, and cancel an instruction.

To change a previously created instruction, cancel it via Cancel the instruction and create a replacement via the Credentials for Instruction API.

To retrieve a payment credential and manage its lifecycle, follow this sequence of API calls. This assumes Card Enrollment is already complete. Each step is broken into the journey steps it fits into, the fields it requires, and the criteria that confirm it succeeded.

Endpoint: POST /vacp/v2/credentials-for-instruction

Journey steps

1. Card enrollment (see Card Enrollment) is already complete; the agent holds a vProvisionedTokenID and device-bound Visa Payment Passkey for the consumer.
2. The consumer provides a purchase instruction and fresh Authentication to the agent (product, merchant, price ceiling, quantity, and validity window). Authentication is sent as assuranceData.
3. The agent converts the purchase instruction into one or more structured payment mandates.
4. The agent calls this endpoint, establishing the instruction and its mandate(s) inline and requesting the first usable payment credential.
5. Visa enrolls the consumer in VIC, then validates the submitted transaction data against the mandate before returning a credential.

Exit criteria

A 200 response with a non-empty instructionId and exactly one of payload.signedPayload or payload.encryptedSignedPayload populated, containing a network token, cryptogram, and ECI value.

A single instruction can hold up to 10 mandates spanning multiple merchants (for example, one combined budget split across two merchants, or separate per-merchant budgets under one consumer authorization). Request the first credential via this endpoint, then use "Retrieve a subsequent payment credential" for each additional mandate under the same instructionId.

How to test

1. Complete Card Enrollment first so you hold a vProvisionedTokenID and device-bound Visa Payment Passkey for the consumer.
2. Build the request with all required fields, choosing a purchaseType that matches the flow under test (PURCHASE_HITL, PURCHASE_AUTONOMOUS, or PURCHASE_RECURRING).
3. Send POST /vacp/v2/credentials-for-instruction over mutual TLS and confirm a 200 response.
4. Confirm the response contains a non-empty instructionId and exactly one of payload.signedPayload or payload.encryptedSignedPayload.

Persist these fields

• instructionId (required for every subsequent credential, confirmation, or cancel call against this instruction)
• The mandateId for each mandate created (required to reference the correct mandate on later credential retrievals)
• payload.paymentAccountReference, when present (not guaranteed to be returned, but useful for reconciliation if it is)

Endpoint: POST /vacp/v2/instructions/{instructionId}/credentials

Journey steps

1. The instruction already exists and is ACTIVE (established via the Credentials for Instruction API).
2. The agent identifies that an additional mandate under the same instruction needs a credential (for example, a multi-merchant or travel pattern such as booking a flight and a hotel as separate credentials under one instructionId).
3. The agent calls this endpoint with a fresh agentSignature and encryptedInstruction, tied to exactly one mandateId.
4. For non-recurring instructions, re-authentication may be required first if the consumer's original authentication is more than one week old (see Consumer Authentication); recurring instructions are exempt for the life of the instruction.

A single instruction can apparently span multiple payment credentials (for example, drawing one mandate against one card and a second mandate against a different card).

Exit criteria

A 200 response with a new credential payload (same shape as the Credentials for Instruction API) for the requested mandate. The instruction remains ACTIVE.

How to test

1. Start from an ACTIVE instruction with at least one additional mandate that hasn't yet had a credential retrieved.
2. Build the request with a fresh agentSignature, a fresh encryptedInstruction, and the target mandateId.
3. Send POST /vacp/v2/instructions/{instructionId}/credentials and confirm a 200 response.
4. Confirm the response contains exactly one of payload.signedPayload or payload.encryptedSignedPayload, and that the instruction status remains ACTIVE.

Persist these fields

• payload.paymentAccountReference, when present (same caveat as the Credentials for Instruction API: not guaranteed to be returned)
• The mandateId used for this call, if you track per-mandate credential history client-side.

Endpoint: POST /vacp/v2/instructions/{instructionId}/confirmation

Journey steps

1. The agent submits the retrieved credential to the merchant checkout flow and attempts the transaction.
2. The agent learns the outcome of the purchase, shipping, or payment event.
3. The agent reports that outcome to Visa via this endpoint. This is required before Cancel can be called if a credential was retrieved, and is especially relevant when an instruction has multiple mandates, since each mandate's disposition is reported independently.
4. If every mandate on the instruction is now complete, the agent sets instructionCompleted=true to close out the instruction.

Exit criteria

A 200 response echoing clientReferenceId. Instruction status becomes COMPLETED if instructionCompleted=true; otherwise it remains ACTIVE. Each mandate's status reflects the submitted mandateReferenceData.status.

Setting transactionStatus=CANCELLED on a confirmationData entry is not the same as calling "Cancel the instruction". It makes that specific tokenized credential unusable for further transactions, but the instruction itself remains ACTIVE and can still be drawn against for other mandates.

How to test

1. Retrieve a credential first (via the Credentials for Instruction API or Retrieve a Subsequent Payment Credential), then submit a confirmationData entry referencing that transaction's transactionReferenceId.
2. Set transactionStatus to APPROVED, DECLINED, PENDING, ERROR, or CANCELLED to match the outcome you're testing.
3. Confirm the response echoes your clientReferenceId with a 200 status.
4. To test instruction completion, resubmit with the top-level completion flag set once every mandate is fulfilled, and confirm the instruction transitions out of ACTIVE.

Persist these fields

Nothing from this call is required as input to a later call, other than being a completed prerequisite before you can call Cancel.

Endpoint: PUT /vacp/v2/instructions/{instructionId}/cancel

Journey steps

1. The instruction must be ACTIVE; Cancel is rejected for any other status, including PENDING, INPROGRESS, or COMPLETED.
2. If any credential was already retrieved against this instruction, "Confirm transaction events" must be called first.
3. The agent calls Cancel to close out the instruction entirely (for example, because the consumer revoked authorization or the purchase instruction is no longer needed).

Confirmation precedes cancellation: Cancel only succeeds while the instruction is ACTIVE. If a credential has been retrieved, Visa requires you to report its outcome via "Confirm transaction events" first (both the retrieved credential's transaction status and the instruction's ACTIVE status must be resolved before Cancel is accepted).

Exit criteria

Instruction status becomes CANCELLED (terminal). No further credential retrievals are permitted for it. Already-issued credentials remain valid for the merchant despite the cancellation.

How to test

1. Confirm the instruction is currently ACTIVE; if a credential was retrieved against it, call "Confirm transaction events" first.
2. Send PUT /vacp/v2/instructions/{instructionId}/cancel with clientReferenceId, client, and appInstance.
3. Confirm the response reflects instruction status CANCELLED, and that a repeat call against the same instructionId is rejected.

Persist these fields

Nothing (cancellation is terminal). Do not reuse this instructionId for further calls; create a new instruction via the Credentials for Instruction API for any replacement purchase.

Retry logic that doesn't account for why a request failed

The most common mistakes stem from retrying without first correcting the underlying condition: retrying an authentication failure without collecting fresh consumer authentication data, retrying against an expired instruction or token instead of creating a new one, and resubmitting a 400-level error without correcting the request.

• Never retry an authentication failure without first collecting fresh authentication data.
• Validate transaction parameters against the consumer's mandate before submitting a request.
• Proactively monitor instruction and token expiration rather than discovering it via a failed call.
• Collect device-fingerprinting data consistently and completely. Incomplete collection is a recurring cause of authentication-assurance failures.