Core concepts

Visa ID & Credential API (VICA) lets you manage consumer identities and payment credentials, and enroll them into multiple Visa products, through one fixed set of endpoints. You select which product an operation applies to using a request attribute — you never call a different endpoint per product.

This page explains the building blocks that are shared across every product. For how the unified APIs sit in front of Visa services, see Overview. For the complete request/response schemas and field constraints, see API Reference.

VICA exposes a single, product-agnostic set of operations. The same operation works across products; the product is chosen in the request body (see Request Patterns).

Supported operations may differ by product; refer to the product-specific documentation for availability.

Two variations of enrollment let you add an already-known consumer (or consumer + payment instrument) to an additional product without resubmitting full details — see Implementation Guides.

VICA also sends two outbound notifications to a registered issuer endpoint: a Request Status Notification when an async request completes, and a Click to Pay Enrollment Attempt Notification - see Core Concepts > Asynchronous Processing Model.

For each operation's HTTP method, path, and request/response samples, see Implementation Guides; for the authoritative schema, see API Reference.

Every VICA request combines target product(s) with consumer and/or payment-instrument data. Individual products extend or constrain these objects, but the shape is shared.

• products selects routing and also determines how results are keyed in responses (productCode vs intent) — see Core Concepts > Request Patterns.
• CARD is supported by all products. BANK_ACCOUNT is supported only by Alias Directory Service (ADS).
• preferredFor (send / receive / pay) applies only to ADS; other products ignore it.

A consumer in VICA is uniquely identified by the combination of two fields:

• externalConsumerID - a unique consumer identifier from the issuer's perspective, generated and provided by you. It is distinct from any payment instrument identifier; one consumer may have many payment instruments.
• externalConsumerIDOwnerBID — the Visa Business Identifier (BID) of the entity that owns that consumer record.

Together they uniquely identify a consumer across the VICA and Click to Pay systems and link enrollment to all later data-management operations, so updates apply to the correct record. Data is siloed per product - enrolling a consumer in one product (e.g., Click to Pay) does not enroll them in another (e.g., AVS).

"consumerInformation": { "externalConsumerID": "829662xw-54pl-50tr-c127-5368r18701", "externalConsumerIDOwnerBID": "10098765", "firstName": "John", "lastName": "Doe", "countryCode": "USA" }

externalConsumerIDOwnerBID identifies the BID of the entity to which an externalConsumerID belongs. When multiple issuers or processors share a VICA integration, this field tells Visa which entity owns a given consumer record.

Phased Requirement

Format

Table 1: externalConsumerIDOwnerBID field constraints

Choosing the right BID. An issuer may have several BIDs associated with a PAN (e.g., the PAN's Issuer BID or its Holding Company BID). Send the BID of the entity that manages the customer profile:

• If you use the same externalConsumerID for cards under different Issuer BIDs, send the PAN's Holding Company BID.
• If you use different externalConsumerIDs for cards under different Issuer BIDs, send the PAN's Issuer BID.

Include this field wherever consumerInformation is accepted — it applies to all products (CTP, AVS, ANI, ADS). For the correct value for your integration, contact your Visa Representative.

Does VICA process requests synchronously or asynchronously? Both - and which one applies depends on the operation. VICA splits operations into two processing modes. Understanding this model is essential - most write operations do not report their final outcome in the HTTP response.

Writes are asynchronous. Enroll, Manage, and Delete return HTTP 202 Accepted to acknowledge receipt, along with a requestTraceId.

The final outcome arrives one of two ways:

• Pull - call Request Status with the requestTraceId. The requestTraceId is a client-provided UUID and is valid for 7 days from receipt.
• Push - receive a Request Status Notification at the endpoint you register in Visa Developer Platform (VDP). Notifications are sent only after processing is fully complete, so every item is in a terminal state (SUCCESS / FAILED). You must build and secure this receiver endpoint - plan for it early. See How to Receive Status Notifications and Authentication & Security › Securing Outbound Notification Endpoints.

Get Data is synchronous. It returns HTTP 200 with the consumer's current data in the response body.

Outcomes are per-product, not per-request. When a request targets more than one product, each product is processed independently. A failure in one product does not fail the others or reject the request at the HTTP level:

• Async writes: inspect the per-product details[] in the Request Status response/notification.
• Get Data: always returns HTTP 200; inspect each item in the data[] array — a product item is either successful data or an errorDetails object.

Note: The same VIDC- reason code can mean different things depending on context (synchronous validation vs. Get Data item-level results). See Errors and Troubleshooting for the authoritative, context-scoped code tables.

VICA also pushes a Click to Pay Enrollment Attempt Notification when a consumer self-enrolls and the issuer is enabled for Issuer Offered Click to Pay (IoC). See Click to Pay with VICA.

How do I target one or more products in a request? You tell VICA which product(s) an operation targets using one of three patterns. The choice affects which fields are required and how results are keyed in responses.

// products only (preferred) "products": [ { "productCode": "CLICK_TO_PAY" }, { "productCode": "ALIAS_DIRECTORY_SERVICE" } ]

Up to four products can be included in one request; each is processed independently.

How the pattern affects responses. In Get Data, Request Status, and Request Status Notification, items are keyed differently depending on the pattern used:

Parse the data / details array accordingly: an item is a CTP result if it carries the intent key, and a non-CTP result if it carries the productCode key. (intent-keyed CTP failures use a top-level error string; product-keyed failures use the structured errorDetails object — see Errors & Troubleshooting.)

Not every operation is available for every product. This matrix is the quick orientation; each product hub documents its own specifics.

¹ ANI requires consumerInformation; it does not support standalone card enrollment.

² Consumer-level operations on AVS return HTTP 422.

³ Get Data on AVS/ANI returns item-level error VIDC-1003; other products in the same request are unaffected.

• Implementation Guides - step-by-step recipes for each operation (enroll, manage, delete, retrieve), with per-product samples.
• API Reference - the complete OpenAPI schema: every endpoint, field, and constraint (optional deeper dive).
• Product guides - deeper, product-specific behavior and constraints: Click to Pay, Address Verification Service, Alias Directory Service, Account Name Inquiry.
• Errors and Troubleshooting - reason codes and how failures surface per operation type.