Alias Directory Service with VICA

Alias Directory Service (ADS) stores and manages payment aliases - associations between a consumer's contact information (such as a phone numbers) and one or more payment instruments. Enrolling consumers and their instruments into ADS lets clients send and receive payments using an alias instead of a full account number.

ADS is unique in two ways among VICA products:

It is the only product that supports BANK_ACCOUNT payment instruments (in addition to CARD).
It supports the preferredFor field, which records how a consumer prefers to use each instrument (send, receive, or pay) for alias-based routing.

How it works

Targeting ADS. Include ALIAS_DIRECTORY_SERVICE in the products array. ADS can be combined with other products in a single request. See Core Concepts › Request Patterns.
Enrollment. Requires consumerInformation and at least one payment instrument, which may be CARD or BANK_ACCOUNT.
Known-consumer enrollment. A consumer already enrolled in another product (for example, Click to Pay) can be added to ADS without resubmitting full consumer information - see How to Enroll a Known Consumer into an Additional Product.
Identity / BID. externalConsumerIDOwnerBID is required for issuers integrated after 3 April 2025 (encouraged for earlier integrations). See Core Concepts › External Consumer ID Owner BID.
Asynchronous processing. Writes return HTTP 202; Get Data is synchronous (HTTP 200) and returns preferredFor and preferredTimestamp where set.

What you can do

A typical ADS integration follows the lifecycle below - select the Alias Directory Service tab on each recipe. ADS supports both CARD and BANK_ACCOUNT instruments and the preferredFor routing preference.

Figure: the typical Alias Directory Service integration lifecycle — enroll a consumer with a card or bank account, retrieve to capture each paymentInstrumentReferenceId and any preferredFor setting, then add, update, or delete instruments as needed.

Enroll a consumer with a card or bank account: How to Enroll Data.
Retrieve the enrolled data: Get Data. Returns preferredFor, preferredTimestamp, and each instrument's paymentInstrumentReferenceId.
(Optional) Add another instrument (card or bank account): Enroll Payment Instruments.
Additional permitted operations:
Add an existing CTP consumer to ADS without re-entering details: Enroll a Known Consumer into an Additional Product.
Update an instrument, including preferredFor: Manage Payment Instruments Data.
Update consumer profile fields: Manage Consumer Information.
Remove an instrument or the consumer: Delete Payment Instruments · Delete Consumer Information.

Supported Operations

Operation	Supported	Notes
Enroll Issuer Data	YES	CARD and `BANK_ACCOUNT`
Enroll Payment Instruments (type=CARD)	YES	N/A
Enroll Payment Instruments (type=`BANK_ACCOUNT`)	YES	N/A
Manage Consumer Information Data	YES	CARD and `BANK_ACCOUNT`; includes `preferredFor` updates
Manage Payment Instruments Data	YES	The country code of the `billingAddress` is required on every Alias Directory Service (ADS) payment credential update
Delete Consumer Information Data	YES	Also deletes associated payment instruments
Delete Payment Instruments Data	YES	CARD and `BANK_ACCOUNT`
Get Issuer Data	YES	Synchronous (HTTP 200); returns `preferredFor` and `preferredTimestamp`
Alias Inquiry	YES	Synchronous (HTTP 200); check if one or more aliases are available for resolution. Returns which aliases can be resolved. Up to 1,000 aliases can be submitted in a single request.
Alias Resolve	YES	Synchronous (HTTP 200); retrieve information about an alias and its associated payment credential(s) to initiate a funds movement transaction.
Alias Confirm	YES	Synchronous (HTTP 200); retrieve information about an alias to confirm the name of the person associated with it, ensuring secure and accurate funds movement transactions prior to initiating them.

For more information on Alias operations, see the Alias Directory Service How To page on Visa Developer Center. Clients should reference only the operations listed in this guide and disregard any other ADS-related content.

Preferred payment instrument (preferredfor)

preferredFor records the consumer's preferred use for each instrument, used by ADS to route alias-based payments. It applies to both CARD and BANK_ACCOUNT instruments in ADS and is optional.

Value	Meaning
SEND	Preferred instrument to send money
RECEIVE	Preferred instrument to receive money
PAY	Preferred instrument to make purchases

preferredFor accepts an array of up to three preference objects; a single instrument can carry more than one preference.
preferredTimestamp is a read-only ISO 8601 timestamp set by ADS, indicating when the instrument was last set as preferred. It is returned in Get Data responses and is not accepted in write requests.
To change, add, or remove preferences, submit an updated paymentInstruments object via Manage Payment Instruments.
Other products (CTP, AVS, ANI) ignore preferredFor; including it in a multi-product request that targets them does not cause an error.

"preferredFor": [ { "type": "SEND" }, { "type": "RECEIVE" } ]

"preferredFor": [
  { "type": "SEND" },
  { "type": "RECEIVE" }
]

Product-specific fields and constraints

Consumer and Profile Fields

Field	Notes
phones[0]	This is the consumer's alias — the permanent key VICA uses to identify them in the Alias Directory. Only the first phone number is stored; up to 5 phone numbers are permitted but only the first one is used. Any additional numbers submitted are ignored. Once enrolled, the alias value (phone number) cannot be changed — attempting to update it returns VIDC-2008.
emails	Email addresses provided will not be stored in Alias Directory.
nationalIdentifiers[0]	Stored as the identification record in Alias Directory. Submit the VICA enum values exactly — they are translated to ADS internal type codes before storage. Supported values: PASSPORT, `DRIVING_LICENSE`, `NATIONAL_IDENTITY`. Additional entries will not be stored in ADS.
countryCode	Required in VICA APIs, but not stored in Alias Directory. `countryCode` is the ISO alpha-3 country code (e.g., USA, GBR, DEU).. Missing or invalid value → VIDC-1001 is returned.
externalConsumerID	The client's own identifier for this consumer (e.g., internal customer ID or user UUID). VICA uses it to look up the corresponding alias in Alias Directory. Must be unique per client and stable across all operations — Manage Consumer, Delete Consumer, Data Retrieval, and all payment instrument operations reference the consumer through this ID. Max 100 chars.
firstName / lastName	Both stored as separate fields in Alias Directory Service. Max 35 chars each. `lastName` is permanently truncated to its first character before storage — see Last Name Privacy Truncation below.
fullName	ADS has no fullName field — it stores `firstName`, `middleName`, and `lastName` separately. Any fullName submitted in a write request will not be stored in ADS. On Data Retrieval, fullName will be derived by joining these three fields with spaces. To control what is returned, submit the individual name fields correctly.
locale	Will not be stored in ADS.
addressLine3	Not supported in Alias Directory. Will not be stored in ADS.

Manage Consumer Behavior

Field Behavior

phones[0] included in request

Field	Behavior
phones[0] included in request	Must exactly match the enrolled alias value. If there is a mismatch, an error will be returned→ VIDC-2008 (HTTP 400) on field `consumerInformation`.`phones[]`. Alias Directory does not allow a phone alias value to be modified after it has been created. Any modifications to the alias value will require the consumer record to be deleted and created with the new phone number.
phones[0] omitted from request	Allowed. Other profile fields are updated in ADS without affecting the stored alias value.
status	Pass ACTIVE or DISABLED to activate or deactivate the consumer enrollment in Alias Directory.

Must exactly match the enrolled alias value. If there is a mismatch, an error will be returned→ VIDC-2008 (HTTP 400) on field consumerInformation.phones[].

Alias Directory does not allow a phone alias value to be modified after it has been created. Any modifications to the alias value will require the consumer record to be deleted and created with the new phone number.

phones[0] omitted from request Allowed. Other profile fields are updated in ADS without affecting the stored alias value.

status Pass ACTIVE or DISABLED to activate or deactivate the consumer enrollment in Alias Directory.

Last Name Privacy Truncation

Field How it is stored in ADS

lastName

Field	How it is stored in ADS
lastName	Applies to the following operations for consumers: Enroll Consumer, Manage Consumer, and Enroll Payment Instrument. The entire `lastName` string is truncated to its first character before being stored in ADS — this applies regardless of how many surnames the value contains (e.g., "Smith" → "S"; "Garcia Lopez" → "G.L."). The full last name is not preserved in ADS. Exceptions can be made for countries requiring full last name. Please contact your Visa representative for more details.
nameOnCard (card instruments)	The last space-separated word is treated as the surname and truncated to its first character before being stored in ADS (e.g., "John Smith" → "John S"; "John Garcia Lopez" → "John G.L.").

Applies to the following operations for consumers: Enroll Consumer, Manage Consumer, and Enroll Payment Instrument.

The entire lastName string is truncated to its first character before being stored in ADS — this applies regardless of how many surnames the value contains (e.g., "Smith" → "S"; "Garcia Lopez" → "G.L.").

The full last name is not preserved in ADS.

Exceptions can be made for countries requiring full last name. Please contact your Visa representative for more details.

nameOnCard (card instruments) The last space-separated word is treated as the surname and truncated to its first character before being stored in ADS (e.g., "John Smith" → "John S"; "John Garcia Lopez" → "John G.L.").

Card Payment Instrument Fields

Only one instrument per enroll payment request. It is necessary to submit additional requests to enroll multiple cards.

Field	Description
cardType	Derived from PAN first digit when absent: "4" → VISA; "5" → MASTER CARD; other → OTHERS. Stored in ADS as-is if provided explicitly.
expirationDate	Submit in yyyy-MM format (e.g., 2027-03).
preferredFor	Stored in ADS. Valid values: RECEIVE, SEND, PAY. It will not be stored in ADS if it is not submitted. It is recommended to included so that the card can be resolved during Alias Resolve.
currencyCode	ISO alpha-3 currency code (exactly 3 characters, e.g., USD, EUR).
issuerName	If not provided, VICA derives the value from the issuer's legal name and stores that in ADS. Provide an explicit value to control what is stored.

Bank account payment instruments

ADS is the only VICA product that supports BANK_ACCOUNT instruments. They are enrolled, updated, retrieved, and deleted with the same operations as cards, with type set to BANK_ACCOUNT.

Required Fields

Field	Description
type	Must be `BANK_ACCOUNT`
accountName	Account holder name as recorded on the account. Max 70 characters.
accountNumber	Bank account number. Max 34 characters.
accountNumberType	IBAN or DEFAULT. Use DEFAULT where IBAN is not supported in the target country.
countryCode	3-character ISO 3166-1 Alpha-3 country code
currencyCode	3-character ISO 4217 Alpha-3 currency code

Optional Fields

Field	Description
bankName	Name of the bank. Max 50 characters.
accountType	CHECKING, SAVING, MAESTRA, VISTA, LOAN
bankIdentifierCode	BIC/SWIFT. Max 11 characters. (Conditional for select markets.)
bankCode	Bank routing code. Max 12 characters. (Conditional for select markets.)
bankCodeType	ABA, `SORT_CODE`, DEFAULT (Conditional for select markets.)
branchCode	Bank branch code. Max 12 characters. (Conditional for select markets.)
address	Address associated with the bank account
preferredFor	Valid values: RECEIVE, SEND, PAY.

Deleting a bank account. Provide only accountNumber, accountNumberType, and accountName alongside the externalConsumerID. The full bank-account object is not required.

Data Retrieval

Field / Scenario	Behavior
Payment credentials unavailable	VICA returns an empty `paymentInstruments` list with warning {"code": "`PARTIAL_DATA`"}. Clients must handle this gracefully — retry or degrade rather than treating it as a fatal error.
`tokenDetails`, `panReferenceID`, `paymentAccountReference`	Not populated in ADS responses. VICA will not return these fields — do not expect them.
`fullName`	Derived from `firstName` + `middleName` + `lastName` (joined with spaces).
`locale`, `countryCode`	Not stored in ADS. Not returned in Data Retrieval responses. Retain these values on the client side if needed.

Behavior When a Consumer Is Disabled

Setting a consumer's status to DISABLED changes how their data is managed in Alias Directory:

The consumer's enrollment in Alias Directory is deactivated; the alias record remains stored but the enrollment is inactive.
You may still enroll additional payment instruments, update existing payment-instrument data, delete the consumer, and delete their payment instruments.
To re-enable a consumer, submit a Manage Consumer request with status = ACTIVE. This restores the enrollment to active status in Alias Directory.
A disabled consumer cannot be found via alias resolution. Any resolve attempt against their alias returns a not-found result until the consumer is re-enabled.

Visa ID and Credential