How to Use Visa Alias Directory
Visa Alias Directory Service
Simplify the push payment experience. Link and resolve an Alias to a payment credential.
How to Use Lifecycle Management, Alias Resolution, and Reporting APIs
Quick Start
A quick introduction for creating and resolving your first Alias.
Step 1
Create an account on Visa Developer and add Alias Directory to your project. Click this link for an example of creating a project and adding APIs.
Step 2
Connect to the Create Alias API in the Sandbox. Use the below code in your Create Alias API request body. Please fill the alias Value prior to submitting the request.
You should receive a successful response like the below. The phone number and card are now linked.
Step 3
Now use the Resolve API to retrieve the Payment Credential. Use the below code in the Resolve API request body.
You should now be able to see the details associated with the Alias in the response.
Step 4
Create an additional Alias for the one created in step 2. The previously created Alias will be the primary Alias, and the one created below will be the secondary Alias. An additional Alias is generated by passing the Alias ID of the primary Alias in the path parameters (752c1fc5-b13b-4903-a725-090601d26f22 in the above example)
Resolving the alias 'johndoe@ gmail.com' should return similar details like those in step 3
Alias Lifecycle Management
Alias Directory allows clients to create Aliases and manage their lifecycle, e.g., update and delete.
Key Terms
| Key Terms | Definitions |
|---|---|
| Participants | - The entities that participate in Alias Directory, e.g. banks. |
| Alias | - An identifier, such as a phone number or email, that represents a customer of a participant. - An Alias has a list of Profiles. |
| Profile | - A Profile identifies a customer for a specific participant with information such as name, address, etc. - A Profile has a list of Payment Credentials. |
| Payment Credential | - This is the payment instrument that is associated with a Profile. - Examples of Payment Credentials are cards and bank accounts. |
| Program | - A list of configurations, such as duplicate resolution rules, that determine the behavior of the Alias Directory for a group of Participants. - For example, separate programs might be created for different regions or countries which require specific configurations to meet market requirements. - All participants will be part of a default Visa program unless there are specific requirements necessary in a particular market. Please contact your implementation manager for more information. |
Data Schema Overview
The below diagram is a simple visual of how this data is mapped in Alias Directory. In the below example
A customer named John has a phone number.
John is a customer of two banks: Bank A and Bank B. Both banks are participating in Alias Directory. John has provided consent to register his information in Alias Directory.
In the Alias Directory database, John has two profiles - one for each bank.
John has a checking account and debit card in each bank and registers them in Alias Directory. In the Alias Directory database, each checking account and debit card is mapped to the respective profile.
John selected his debit card at Bank A as his preferred Payment Credential.
Alias Lifecycle Management APIs Overview
| API | Description |
|---|---|
| Create Alias | - This creates an Alias record which consists of a Profile and Payment Credential(s). - Multiple Payment Credential types can be added with a Create Alias call. However, only one of each Payment Credential type can be added with a Create Alias call. For example, a Create Alias call can include a card and bank account. However, it cannot include two bank accounts. A second bank account can be linked to the same Alias using the Add Payment Credentials API. - Please refer to the below format when using phone number or payname as an Alias type: Phone number should be provided in accordance with ITU-T E.164 (2010) number structure. Please note that in the E.164 format, the "+" sign is not included. Below are some examples of phone numbers with different country codes: United States (country code = 1): 1650xxxxxxx Ukraine (country code = 380): 38067xxxxxxx United Kingdom (country code = 44): 4478xxxxxxxx Visa payname format: “+personalidentifier.domain" [must be min 4 and max 49 characters] Prefix '+' : Consumers of Alias Directory APIs must send all paynames with the ‘+’ sign as the first position of the field. Personal Identifier : Can be defined by the Consumer or suggested by the Participant. Delimiter '.' : Separates the personal identifier from the domain. Domain : Participant on the receive side selects the domain during the enrollment process. Allowed characters: Accented: é - accent acute, è - accent grave, ê – circumflex, ë - umlaut or diaerisis, ç – cedilla, ñ – tilde, ø – streg, ð - eth (capital form Ð), å – bolle, æ – ligature, œ – ligature, ē – macron, č – háček, ŭ – crescent Special characters : Dot / period, Comma, Hyphen, Apostrophes (of the N and the ’ variety), Spaces, Underscore |
| Create Additional Alias | - This API generates an additional Alias associated with the primary Alias, whose ID is specified in the API request path parameters. - A resolve call on the additional (secondary) Alias will return the profile and payment details of the primary Alias since the secondary Alias pertains to the same individual and is linked to the same credentials. - Deleting the primary Alias will also delete the secondary Alias. However, deleting the secondary Alias will not affect the primary Alias. |
| Update Alias | - Updates the information in the Alias. Only the entity which has the appropriate permissions can make any edits to the Alias information. In the above example, only “Bank A” can edit “Bank A” information. “Bank A” cannot edit “Bank B” information. - This API will allow updates the Profile, Identification, and Consent objects. - Any updates to Payment Credentials should be done with the Update Payment Credentials API. - This API replaces the target resource with the content in the request payload, including omitted fields. Clients should perform a GET Alias request prior to using this API. |
| Delete Alias | - Deletes a particular Alias. Only the entity which has the appropriate permissions can delete this Alias. In the above example, only “Bank A” can delete the Alias information with “Bank A”. “Bank A” cannot delete “Bank B” information. - If an Alias is deleted, then all Payment Credentials associated with that Identity will also be deleted. In the above example, if “Bank A” deletes John’s phone, then John’s Alias and Payment Credentials with Bank A will also be deleted. “Bank B” information will not be impacted. |
| Create Payment Credential | - Adds a Payment Credential to an existing Alias. This is used when there may be multiple Payment Credentials such as checking account, savings account, debit card, etc. associated with an Alias. |
| Get All Payment Credentials | - Retrieve all the Payment Credentials associated with an Alias. - In the above example, if Bank A called this API, then the response would contain the card and bank Payment Credentials associated with John at Bank A. - Clients who are configured as non-PCI compliant are supported through the use of tokenization for this API. If a token is available, the PAN will be replaced with the token in the accountNumber field in the response. If no token is available, PCI information will be removed from the response, and neither a token nor the PAN will be returned. |
| Get Payment Credential | - Retrieve a single, specific Payment Credential associated with an Alias. - In the above example, Bank A can call this API to only retrieve the information for the card Payment Credential. - Clients who are configured as non-PCI compliant are supported through the use of tokenization for this API. If a token is available, the PAN will be replaced with the token in the accountNumber field in the response. If no token is available, PCI information will be removed from the response, and neither a token nor the PAN will be returned. |
| Update Payment Credential | - Update a Payment Credential associated with an existing Alias. - This API can also be used to update the preferred Payment Credential associated with an Alias. - This API replaces the target resource with the content in the request payload, including omitted fields. Clients should perform a GET Payment Credential request prior to using this API. |
| Delete Payment Credential | - Deletes a Payment Credential associated with an Alias. |
Alias and Payment Credential Status
Possible Alias statuses:
| Status | Comments |
|---|---|
| Active | - An active Alias can be used for Alias Lifecycle Management and Alias Resolution |
| Deleted | - This status occurs when a participant deletes their Alias - This status is internal. Once an alias is deleted, it cannot be made Active or retrieved via any API call. If the same Alias is needed in the future, it must be created again. |
| Blocked | - This status occurs when an Alias is blocked for suspected fraud, suspicious behavior, or findings on sanctions screening. In these cases, Alias Directory will automatically set the Alias as blocked. |
| Disabled | - A client can manually set an Alias as disabled and not be used for Alias resolution. This is up to the client’s discretion. - The client can update the status from disabled back to Active. - This can be done via the Update Alias Status API. |
| Expired | - This status occurs when an Alias has not been used within a specific time period. This is up to the client’s discretion. - The client can update the status from expired back to Active. - This can be done via the Update Alias Status API. |
Possible Payment Credential statuses:
| Status | Comments |
|---|---|
| Active | - An active Payment Credential can be used for Alias Lifecycle Management and Alias Resolution |
| Deleted | - This status occurs when the Payment Credential is deleted - This status is internal. Once a Payment Credential is deleted, it cannot be made Active or retrieved via any API call. If the same Alias is needed in the future, it must be created again. |
| Blocked | - This status occurs when a Payment Credential is blocked for suspected fraud, suspicious behavior, or findings on sanctions screening. In these cases, Alias Directory will automatically set the Payment Credential as blocked. |
| Disabled | - A client can manually set an Alias as disabled and not be used for Alias resolution. This is up to the client’s discretion. Once Alias is disabled, all associated Payment Credentials will also be disabled. - The client can update the Alias status from disabled back to Active. This will set the associated Payment Credentials activate as well. - This can be done via the Update Alias Status API. |
| Expired | - This status occurs when an Alias has not been used within a specific time period. This is up to the client’s discretion. Once Alias is disabled, all associated Payment Credentials will also be expired. - The client can update the status from expired back to Active. - This can be done via the Update Alias Status API. |
External ID
Overview
Alias Directory offers clients a number of options for managing their Alias records. Clients may already have an existing id used for their consumer's Alias data and can reuse that id as an externalId.
In the Create Alias call, an id; is returned for the Alias (Line 2) and for each Payment Credential (Line 6 & 12). Each id is internally generated by Alias Directory and used for identifying each record. Clients can provide an externalId during the Create Alias API and each externalId will be associated with an internal id
Alias Resolution
Overview
There are three APIs within the Alias Resolution bundle
- Alias Resolution
- Alias Inquiry
- Alias Confirm
Search Options
Alias Types
Alias Directory currently supports the following Alias types: Phone, Email, DirectoryAliasID, and Payname.
Filters
Alias Directory supports a number of filters which can be applied to the Alias Resolution request.
Transaction Details
currencyCode
User Details
- This object allows the client initiating an Alias Inquiry or Alias Resolution call to provide more information about the consumer requesting the information.
Setting a Preferred Payment Credential
- Alias Directory allows a Payment Credential to be marked as “Preferred”.
Duplicate Resolution
- A common scenario that occurs is that a consumer may use the same Alias (e.g., phone) and register that Alias with multiple participants.
Tokenization
Integration with Cybersource Token Management Service
On Behalf Of Processing
Overview
On-Behalf-Of processing allows processors, or technical service providers (TSPs) to enable the Visa Alias Directory Service for multiple clients using a single project on Visa Developer Center.
Reporting
Alias Directory Service provides APIs for requesting and downloading reports. The available endpoints are listed below
| Step | Endpoint | Description | Additional Details |
|---|---|---|---|
| Create Report | /reports (POST) | Create a report, specify the report type and define the parameters. Report ID is returned in response. |
The field type specifies the type of report to be generated - RESOLUTIONRECONCILIATION - DIRECTORYSTATUS - PAYMENTCREDENTIALDETAIL - PLATFORMREQUESTS - DIRECTORYACTIVITY The field filters defines the parameters used to create the report (e.g., startDate, endDate) Alias Directory will create the report offline and clients can download in the subsequent steps. |
| Get Report | /reports/{reportId} (GET) | Retrieves information about a specific Create Report request. | Clients can use this endpoint to check the status of a Create Report request. For example, the create report request may be “completed” or “in-progress” The response of this will also include the field "fileIds". The fileId will be used to download the report. Please note some reports may have multiple files due to the size of the report. |
| Download Report | /reports/{reportId}/file/{fileId} (GET) | Retrieves a file from a previously requested report with COMPLETED status. | This endpoint returns the requested data in JSON format, as described in the API spec, as part of the MLE encrypted response payload. |
Resolution Reconciliation Report
Report Description:
- Includes a detailed view of the Alias Resolutions requests of a participant. For example, if participant has made ten Alias Resolution requests, this report details the status and results of each request.
Report Fields:
| Field Name: originationDateTime | Description: The date and time of the Alias Resolution request | Field Name: programId | Description: The guid of the program that the participant belongs in | Field Name: originatorActorId | Description: Participant id of the entity which sent the request | Field Name: onBehalfOf | Description: Participant id which the original_actor_id sent the request on behalf of. This is only applicable in certain cases. | Field Name: resolvedAlias | Description: The Alias value provided in the Alias Resolution request | Field Name: resolvedPaymentCredentialType | Description: The type of Payment Credential returned in the Alias Resolution response | Field Name: statusCode | Description: The status code returned in the API response | Field Name: resolvedDirectory | Description: The name of the directory which returned the Payment Credential
Directory Status Report
Report Description:
- Includes the cumulative number of Aliases and Payment Credentials stored in the Alias Directory.
Report Fields:
| Field Name: programId | Description: The guid of the program that the participant belongs in | Field Name: ownerParticipantId | Description: The participant id which owns this Alias and Payment Credential information | Field Name: objectType | Description: The type of this object | Field Name: status | Description: The status of this object | Field Name: objectCount | Description: The number of types this object is in the Alias Directory
Payment Credential Details
Report Description:
- Provides a detailed view of the Payment Credentials stored in the Alias Directory. Each row is a Payment Credential.
Report Fields:
| Field Name: paymentCredentialCreatedDateTime | Description: The time the Payment Credential was created | Field Name: programId | Description: The guid of the program that the participant belongs in | Field Name: ownerParticipantId | Description: Participant id which created the Payment Credential | Field Name: paymentCredentialId | Description: The internal ID of the Payment Credential | Field Name: paymentCredentialType | Description: The type of the Payment Credential | Field Name: accountNumberLast4 | Description: The last four digits of the account | Field Name: paymentCredentialStatus | Description: The status of the Payment Credential | Field Name: aliasId | Description: The internal ID of the Alias associated with this Payment Credential | Field Name: aliasValue | Description: The value of the Alias associated with this Payment Credential | Field Name: aliasType | Description: The type of Alias
Platform Requests Report
Report Description:
- Provides a view of the cumulative number of requests received in the Alias Directory.
Report Fields:
| Field Name: programId | Description: The guid of the program that the participant belongs in | Field Name: originatorActorId | Description: Participant id of the entity which sent the request | Field Name: onBehalfOf | Description: Participant id which the original_actor_id sent the request on behalf of. This is only applicable in certain cases. | Field Name: operationType | Description: The type of operation the report must include. | Field Name: statusCode | Description: The status code returned in the API response | Field Name: operationsCount | Description: The aggregated amount of the number of requests
Resolution Directory Activity Report
Report Description:
- Includes a detailed view of the Alias Resolutions requests received by a directory. This report is from the perspective of the directory itself and includes both local and remote directories.
Report Fields:
| Field Name: resolveDirectory | Description: The directory which received the Alias Resolution requests. | Field Name: programId | Description: The guid of the program that the participant belongs in | Field Name: originatorActorId | Description: Participant id of the entity which sent the request | Field Name: onBehalfOf | Description: Participant id which the original_actor_id sent the request on behalf of. This is only applicable in certain cases. | Field Name: operationType | Description: The type of operation the report must include. | Field Name: statusCode | Description: The status code returned in the API response | Field Name: requestCount | Description: Total number of Alias Resolution requests