alias directory service technical specifications guide v3.0-final · 2019. 2. 1. · $oldv...

Alias Directory Service Technical Specifications Version 3.0

24 August 2018

Important Information on Copyright

© 2018 Visa. All Rights Reserved.

The trademarks, logos, trade names and service marks, whether registered or unregistered (collectively the “Trademarks”) are Trademarks owned by Visa. All other trademarks not attributed to Visa are the property of their respective owners.

Note: This document is not part of the Visa Core Rules. In the event of any conflict between any content in this document, any document referenced herein, any exhibit to this document, or any communications concerning this document, and any content in the Visa Core Rules, the Visa Core Rules shall govern and control.

No Warranty:

This Alias Directory Service and any services provided in connection with the such service are provided on an as-is basis and Visa makes no warranty or representation of any kind, including as to the accuracy or availability of the Alias Directory Service, the Alias Directory Service Technical Specifications, or the currentness or completeness of the information or content provided therein.

Disclaimer:

This Alias Directory Service Techical Specifications is strictly for informational purposes only. The Visa client must ensure that all necessary licenses, registrations, notifications, authorizations, and approvals necessary to utilize the Alias Directory Service, including in the collection of any alias, are obtained from the competent authorities.

For More Information

Note: For more details on Visa Direct Service or about this guide, please contact your Visa Client Support Services Representative.

Note: “Visa Direct” is the brand name for the funds transfer services enabled by the Original Credit Transaction (OCT) described in this guide. Any and all references to “Visa Direct” in this and other documents and materials refer to the OCT transactions described in this guide.

Alias Directory Service - Technical Specifications

24 August 2018 3

Contents

Tables ................................................................................................................................................................. 4

About This Document .................................................................................................................................................. 5

Audience ....................................................................................................................................................................................... 5

Key Terms ..................................................................................................................................................................................... 5

Related Publications................................................................................................................................................................. 7

1 Alias Directory Service (ADS) Overview ...................................................................................................... 8

2 Batch File Processing ....................................................................................................................................... 8

2.1 Batch File Processing Overview ................................................................................................................................. 8

2.2 Using Visa Online (VOL) for File Upload ................................................................................................................ 9

2.3 Batch File Specifications ............................................................................................................................................... 9

2.3.1 Batch File Naming Convention .......................................................................................................................... 9

2.3.2 Encryption and Transmission ............................................................................................................................ 10

2.3.3 Consumer Alias File .............................................................................................................................................. 10

2.3.3.1 Consumer Alias File Format ......................................................................................................................... 10

2.3.3.2 Consumer Alias Response File .................................................................................................................... 13

2.3.4 Merchant Alias File ............................................................................................................................................... 13

2.3.4.1 Merchant Alias File Format .......................................................................................................................... 14

2.3.4.2 Merchant Alias Response File ..................................................................................................................... 16

2.3.5 Agent Alias File....................................................................................................................................................... 16

2.3.5.1 Agent Alias File Format ................................................................................................................................. 16

2.3.5.2 Agent Alias Response File ............................................................................................................................ 19


Tables

Table 1: Key Terms .............................................................................................................................................................. 5

Table 2: Related Publications .......................................................................................................................................... 7

Table 3–1: Consumer Alias File Format ......................................................................................................................... 10

Table 3–7: Merchant Alias File Format ........................................................................................................................... 14

Table 3–12: Agent Alias File Format .................................................................................................................................. 16


24 August 2018 5

About This Document

The Alias Directory Service (ADS) Technical Specifications Document includes batch file processing specifications and instructions for use by new and continuing Visa push payment participants implementing the Alias Directory Service.

ADS provide services to resolve an identifier (i.e. an alias) such as mobile phone number, email address, short name, or nickname, to a Visa card account. A Visa client can use ADS to allow consumers provide an alias instead of inputting a card number (PAN) to use Visa Direct push payment services.

Audience

This Guide is intended to provide IT management and technical personnel with basic information to assist them with the implementation of ADS. The technical content is intended for engineers who are responsible for network equipment and system configuration. It is assumed that personnel have a basic understanding of security key management such as PGP and Visa Direct Original Credit Transaction (OCT) funds transfer & merchant payment transactions services.

Key Terms

Table 1: Key Terms

Term Definition

Acquirer Acquirers and Acquirer processors that process push payment transactions to merchants and agent cash deposits and withdrawals.

A Visa financial institution approved by Visa that sponsors a Merchant or Service Provider and directly or indirectly enters Visa Direct transactions (AFTs and/or OCTs) into interchange.

Agent An entity that provides account-related services, such as account withdrawals (cash-out) and deposits (cash-in) services to consumer.

Business Application Identifier (BAI) A data element provided on an OCT message that is used to identify the type of OCT (e.g., money transfer, funds disbursement, prepaid load, or credit card bill payment).

Business Application Identifier that is used to identify program’s business application type for VisaNet transaction processing.

For Alias based push payment transactions, it supports the following valid values :


Term Definition

PP = Person to Person

MP = Merchant Payment

CO = Cash Out

CI = Cash In

Issuer In the context of this guide, the Visa client financial institution that has issued the recipient’s Visa card and processes Visa payment transactions. The Issuer receives the OCT and credits the recipient’s Visa account with the funds.

Merchant Merchants that accept QR push payment transactions at their point-of-sale.

In terms of Visa Direct OCTs, an entity that receives OCTs as payment for goods and services from customers. Merchants can be sponsored directly by an Acquirer or on boarded through an Acquirer sponsored Service Provider.

Original Credit Transaction

(OCT)

The Original Credit Transaction (OCT) is a VisaNet/Visa systems transaction that can be used to send funds to an eligible Visa account. Visa Acquirers, service providers, and merchants can use the OCT to enable Visa Direct services such as money transfers, funds disbursement, prepaid loads, and credit card bill payments.

Payee / Receiver Person / Entity that receive funds from a push payment transaction. The funds are credited to the payee’s account.

The entity can be a consumer, merchant or an agent.

Payer / Sender Person / Entity that sends a push payment transaction with funds made available from the underlying payer account. The funds are debited from the payer’s account.

The entity can be a consumer.

Service Provider An Acquirer sponsored third party entity that enables Original Credit Transaction (OCT)- based services on behalf of an Acquirer or offers OCT-based services to Merchants.

Visa Direct Visa Direct is a product platform that includes the OCT transaction and associated operating rules and guidelines that allow clients to create push payment services (e.g., money transfers, funds disbursements, etc.).

Visa Online Service

(VOL)

Visa Online (VOL) is Visa’s business-to-business portal that offers secured access to information, tools and services, and is designed to support clients’ needs to do business with Visa.


24 August 2018 7

Related Publications

Table 2: Related Publications

Title Description

Alias Directory Service Implementation Guide

This implementation guide provides an enhanced overview of Alias Directory Service, implementation requirements and guidelines for Issuers and Acquirers to deploy alias functionality.


1 Alias Directory Service (ADS) Overview

ADS provide services to map and resolve an identifier; referred as an “Alias” such as mobile phone number, email address, short name, or nickname, to a card account PAN. A Visa client can use ADS to allow consumers to initiate push payments using an Alias instead of a card number (PAN) for push payment services such as person-to-person (P2P) money transfers, merchant payments, and cash deposits and cash withdrawals.

In an increasingly digital world, the payment industry is evolving and gradually shifting from card-based to digital form factors of payment. Consumers are getting used to interacting by using Aliases (e.g. mobile number, email, social ID, etc.), a form of digital identity, to access electronic services provided by different industries such as payment, social media, financial services, and government. Visa aims to enable Acquirer and Issuers to offer their customers simple and safe payment experience with its push payment solutions.

2 Batch File Processing

2.1 Batch File Processing Overview

Alias Directory Service provides batch file processing capabilities to Issuers and Acquirers to perform alias lifecycle management using batch files.

For Issuers:

Their system and operation procedures should be enhanced to support including but not limited to the following:

Consumer Alias File: Collate consumer data with alias information into a batch file. Consumer data including consent may be collected by the Issuer from different means, e.g. bank branches, mobile app, etc.

For Acquirers:

Their system and operation procedures should be enhanced to support including, but not limited to, the following: Merchant Alias File: Collate merchant data with alias information into a batch file. Merchant data

should be collected during sign-up and alias created when PAN is generated for merchant. Agent Alias File: Collate agent data with alias information into a batch file. Agent data should be

collected during sign-up and alias created when PAN is generated for agent.


24 August 2018 9

2.2 Using Visa Online (VOL) for File Upload

To use the ADS file upload functionality for managing aliases, staff from Issuers and Acquirers should visit Visa Online (VOL) to access this functionality. A unique shared secret key (256-bit key length) is generated by Visa that is distributed to the Issuer/Acquirer via the Visa representative during onboarding. The shared secret key together with the initialization vector (IV) generated by ADS in VOL is required to encrypt the batch file containing the alias and related customer data at the Issuer/Acquirer’s end prior to uploading the encrypted batch file to ADS for processing.

Contact Visa’s representative for details.

2.3 Batch File Specifications

2.3.1 Batch File Naming Convention

Alias Directory Service supports batch file processing of three types of alias batch files, namely consumer, merchant, and agent alias files. The batch files are in comma separated value (CSV) format with file encoding in UTF-8 or ANSI, and each file can contain a maximum of 20,000 records. The batch files with sensitive data (e.g. PII data) are required to be encrypted by Issuers and Acquirers with extension of .cbc prior to uploading to ADS via VOL; otherwise, CSV format will be used. The batch files use the following naming convention:

{BID}-{UsageCode}-{CustomerType}-{YYYYMMDD}-{SEQ}.cbc

where

{BID} is the Business ID of your organization in Visa.

{UsageCode} is the usage of the file:

- “ALS” for managing alias life cycle

{CustomerType} Valid alias customer

- “CNR” for consumer;

- “MCT” for merchant; or

- “AGT” for agent

{YYYYMMDD} is the local calendar date of year, month and day. If MM or DD is less than 10, a leading “0” is added.

{SEQ} is sequence number of batch file for a day, 6-digit from 000001 to 999999, reset at each day.

Following are some examples of batch filenames.


- 82412-ALS-CNR-20170731-000013.cbc (encrypted Consumer alias file) - 123456-ALS-MCT-20170628-000001.cbc (encrypted Merchant alias file) - 33336-ALS-AGT-20170801-000001.cbc (encrypted Agent alias file)

When Issuers or Acquirers upload the files via Visa Online (VOL), ADS performs simple validation of the files such as file naming convention, file format, etc., and generates error codes in the response if errosr are detected. Refer to Section 3.3.6 “Error Response File for Batch File Processing” for details.

2.3.2 Encryption and Transmission

Issuers and Acquirers are required to be onboarded in Alias Directory Service Service to use batch processing service for managing alias lifecycle. A unique shared secret key (256-bit key length) is generated by Visa which is then distributed to Issuer/Acquirer via Visa representative during onboarding.

Issuer/Acquirer use the assigned shared secret key together with Initialization Vector (IV) to encrypt the batch file prior to transmission to Alias Directory Service via VOL. When the Issuer/Acquirer logs on to VOL to access ADS web interfaces for uploading the file, the IV will be generated and displayed. The Issuer/Acquirer should use this IV and the shared-secret key to encrypt the ADS batch file. During uploading of batch file, the ADS web interfaces to insert the IV in the header request to ADS for decryption, validation and persistence.

The encryption algorithm for Visa Alisa Directory is AES-CBC Cipher Algorithm with 256-bit key. During upload, Issuer/Acquirer needs to provide the encrypted file and IV via VOL.

2.3.3 Consumer Alias File

2.3.3.1 Consumer Alias File Format

Table 2–1: Consumer Alias File Format

Field Type Required / Conditional / Optional

Description

formatVersion String Required File format version used

Default = “1.0”


24 August 2018 11


Description

action Enum Required Submit as per instruction for ADS to process the alias record.

Below are valid actions:

“CREATE” = create a new alias in ADS

“UPDATE” = update information of an existing alias in ADS

“DELETE” = delete the alias from ADS

Note:

If action = “CREATE”, only one field “guid” or “newGuid” should be populated for the record.

If action = “DELETE”, populate “guid” only.

guid String Conditional This attribute is uniquely used by Issuer to identify their customer (i.e. consumer cardholders) in their system.

Note:

If action = “CREATE” and guid is present in the record, only fields “aliasesAlias” and “aliasesType” are required for the consumer alias record in CSV file.

Issuer may pass their existing unique identifier of a cardholder of their system to ADS as a guid.

For multiple aliases linked to the same PAN, different guids should be provided.

newGuid String Conditional New unique identifier generated by issuer for a consumer if issuer would like to change the existing guid to a new value.

recipientFirstName String Conditional Consumer’s first name.

recipientMiddleName String Optional Consumer’s middle name.

recipientLastName String Required Consumer’s last name.

address1 String Optional Address line 1

address2 String Optional Address line 2



Description

city String Conditional Consumer’s city

country String Conditional Consumer’s country code as defined by ISO 3166.

postalCode String Optional Consumer’s postal code

contactPhoneNumber String Optional Consumer’s contact phone number for all communications

contactEmail String Optional Consumer’s contact email for all communications

consentDateTime String Optional Date & time when consumer has provided their consent to Issuer about the use of their personal data for ADS service.

This field can remain unpopulated.

Format: YYYY-MM-DD HH:NN (HH:NN can be blank)

Local date and time should be converted to Coordinated Universal Time (UTC).

recipientPrimaryAccountNumber String Conditional Consumer’s card number

issuerName String Conditional This is the Issuer name of recipient’s card

cardType String Conditional Card type description. Reference to Field 62.23—Product ID of available card products.

e.g. Visa Platinum

aliasesAlias String Conditional Consumer alias.

e.g. phone number, email address, etc.


24 August 2018 13


Description

aliasesType String Conditional “01” – Phone number

“02” – Email address

If phone number is used for alias, the alias should be provided in accordance with ITU-T E.164 (2010) number structure.

Below are some examples of phone numbers with different country codes:

Country Country Code

Examples

United States 1 1650xxxxxxx

Russia 7 7495xxxxxxx

United Kingdom

44 4478xxxxxxxx

Singapore 65 659xxxxxxx

Hong Kong 852 8529xxxxxxx

Kenya 254 254701xxxxxx

Contact Visa’s representative if sample batch file is needed.

2.3.3.2 Consumer Alias Response File

During batch file upload and processing, ADS parses and validates the input files. If there are any validation errors, an error response file in CSV format is generated and returned to Issuer/Acquirer for triage.

Please note that if an error is detected in the input batch file, ADS will not process the file. It is the Issuer/Acquirer’s responsibility to fix all the errors shown in the response file prior to reloading the batch file to ADS for processing.

The error response file will have the row number, fieldname, and description of all the validation errors. There will be no personal identification information (PII) in the error description in the response file and hence there is no encryption of the response file. The Issuer/Acquirer can then download the error response file, fix the original input batch file, and re-submit it to ADS.

Contact Visa’s representative if sample response file is needed.

2.3.4 Merchant Alias File


2.3.4.1 Merchant Alias File Format

Table 2–2: Merchant Alias File Format

Attribute Name Type Required / Conditional / Optional

Description


Default = “1.0”


Below are valid action types:



“DELETE” = delete the alias form ADS

aliasId String Required Uniquely assigned by Acquirer to a merchant.

mVisaMerchantId String Required Mobile Push Payment merchant ID.

16-digit long number as per Mobile Push Payment Program Implementation Guide.

merchantCategoryCode String

Size=4

Conditional Merchant Category Code.

acquirerBid String Required Business ID of the Acquirer registered in Visa.

payloadFormatIndicator String Required Defines the format of the merchant data payload. For this version of the merchant data payload, the Payload Format Indicator shall have the value "01". This value is not populated in the VisaNet message.


24 August 2018 15


Description

pointOfInitiationMethod String

Size=2

Optional In this two-digit field, the first character indicates the method by which the data is presented by the merchant. The second character indicates whether the data is static or dynamic. Static data refers to a situation wherein same data is presented for every transaction unlike a dynamic data wherein the information is specific to a transaction.

1st Character:

“1” = QR

“2” = BLE

“3” = NFC

“4”-“9” = Reserved for future use

2nd Character:

“1” = Static

“2” = Dynamic


Example: “11” indicates QR static code, “12” indicates QR dynamic code.

transactionCurrencyCode String Required As defined by ISO 4217.

This is the transaction currency code that a merchant can accept for payment.

tipConvenienceFeeIndicator String Optional Tip or Convenience Fee Indicator.

convenienceFeeAmount String Optional The convenience fee of a fixed amount.

The format of the amount is the same as defined in tag 54.

convenienceFeePercentage String Optional The percentage convenience fee, specified as numeric value from “00.01” (for 00.01%) to “99.99” (for 99.99%).

recipientName String Required Merchant’s name.

city String Required Merchant’s city

country String Required Merchant’s country code as defined by ISO 3166.

postalCode String Optional Merchant’s postal code



Description

email String Optional Merchant’s email address

phone String Optional Merchant’s phone number


2.3.4.2 Merchant Alias Response File

During batch file upload and processing, ADS to parse and validate the input files. If there are any validation errors, an error response file in CSV format to be generated and returned to Issuer/Acquirer for triage.

Please note that if error is detected in the input batch file, ADS will not process the file. It is Issuer/Acquirer’s responsibility to fix all the errors shown in the response file prior to reload the batch file to ADS for processing.

The error response file will have the row number, fieldname and description of all the validation errors. Merchant alias information contains all business information data and hence there is no encryption of the response file. The Issuer/Acquirer can then download the error response file, fix the original input batch file and re-submit it to ADS.

2.3.5 Agent Alias File

2.3.5.1 Agent Alias File Format

Table 2–3: Agent Alias File Format


Description


Default = “1.0”


24 August 2018 17


Description


Below are valid action types:



“DELETE” = delete the alias form ADS

aliasId String Required Uniquely assigned by Acquirer to an agent.

mVisaAgentId String Required Mobile Push Payment agent ID.

16-digit long number as per Mobile Push Payment Program Implementation Guide.

merchantCategoryCode String

Size=4

Conditional Merchant Category Code of an agent.

acquirerBid String Mandatory Business ID of the Acquirer registered in Visa

payloadFormatIndicator String Mandatory Defines the format of the agent data payload. For this version of the agent data payload, the Payload Format Indicator shall have the value "01". This value is not populated in the VisaNet message.



Description

pointOfInitiationMethod String

Size=2

Optional In this two-digit field, the first character indicates the method by which the data is presented by the merchant. The second character indicates whether the data is static or dynamic. Static data refers to a situation wherein same data is presented for every transaction unlike a dynamic data wherein the information is specific to a transaction.

1st Character:

“1” = QR

“2” = BLE

“3” = NFC


2nd Character:

“1” = Static

“2” = Dynamic


Example: “11” indicates QR static code, “12” indicates QR dynamic code.

transactionCurrencyCode String Mandatory As defined by ISO 4217.

This is the transaction currency code that an agent can accept for payment.

recipientName String Mandatory Agent’s name.

city String Mandatory Agent’s city

country String Mandatory Agent’s country code as defined by ISO 3166.

postalCode String Optional Agent’s postal code

email String Optional Agent’s email address

phone String Optional Agent’s phone number



24 August 2018 19

2.3.5.2 Agent Alias Response File

During batch file upload and processing, ADS to parse and validate the agent batch file. If there are any validation errors, an error response file in CSV format to be generated and returned to Issuer/Acquirer for triage.

Please note that if error is detected in the input batch file, ADS will not process the file. It is Issuer/Acquirer’s responsibility to fix all the errors shown in the response file prior to reload the batch file to ADS for processing.

The error response file will have the row number, fieldname and description of all the validation errors. Agent alias information contains all business information data and hence there is no encryption of the response file. The Issuer/Acquirer can then download the error response file, fix the original input batch file and re-submit it to ADS.

Contact Visa’s representative if sample response file is needed.

alias directory service technical specifications guide v3.0-final · 2019. 2. 1. · $oldv...

Documents