visa offers platform - visa developer center€¢ technical specification and requirements for...

Visa Offers Platform Enrollment API

August 2016

Visa Confidential

Important Information on Confidentiality and Copyright

© 2016 Visa. All Rights Reserved.

Notice: This information is proprietary and CONFIDENTIAL to Visa. It is distributed to Visa participants for use exclusively in managing their Visa programs. It must not be duplicated, published, distributed or disclosed, in whole or in part, to merchants, cardholders or any other person without prior written permission from Visa.

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 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 Rules, the Visa Rules shall govern and control.

Contents

August 2016 Visa Confidential i

Contents

Contents ............................................................................................................................................................................ i

Figures ..............................................................................................................................................................................ii

Tables .............................................................................................................................................................................. iii

About This Guide .......................................................................................................................................................... 1

Purpose ......................................................................................................................................................................................... 1

Audience ....................................................................................................................................................................................... 1

Requirements .............................................................................................................................................................................. 1

1 Overview ................................................................................................................................................................. 2

2 Technical Specifications ...................................................................................................................................... 2

2.1 User and Card Enrollment ........................................................................................................................................... 3

2.1.1 Enroll Request........................................................................................................................................................... 3

2.1.2 Enroll Response ..................................................................................................................................................... 12

2.1.3 Enroll Errors ............................................................................................................................................................. 17

2.2 Add Card to Existing Profile ...................................................................................................................................... 19

2.2.1 SaveCard Request ................................................................................................................................................. 19

2.2.2 SaveCard Response .............................................................................................................................................. 20

2.2.3 SaveCard Errors ...................................................................................................................................................... 23

2.3 Remove Card from Existing Profile ........................................................................................................................ 24

2.3.1 DeleteCard Request ............................................................................................................................................. 24

2.3.2 DeleteCard Response .......................................................................................................................................... 25

2.3.3 DeleteCard Errors .................................................................................................................................................. 27

2.4 Unenroll - Remove User Profile ............................................................................................................................... 28

2.4.1 Unenroll Request ................................................................................................................................................... 28

2.4.2 Unenroll Response ................................................................................................................................................ 29

2.4.3 Unenroll Errors ....................................................................................................................................................... 30

2.5 Batch Enrollment ........................................................................................................................................................... 31

A Data Dictionary ................................................................................................................................................... 35

B Fields ...................................................................................................................................................................... 36

Figures

ii Visa Confidential August 2016

Figures

Figure 2-1: Sample Enroll Request by Card Information ................................................................................................ 7

Figure 2-2: Sample Enroll Request by TransactionInfo Using a Transaction Id ..................................................... 8

Figure 2-3: Sample Enroll Request by TransactionInfo Using Transaction Details ............................................. 10

Figure 2-4: Sample Enroll Response ..................................................................................................................................... 15

Figure 2-5: Sample Enroll Error Response .......................................................................................................................... 16

Figure 2-6: Sample SaveCard Requesrt ............................................................................................................................... 20

Figure 2-7: Sample SaveCard Response ............................................................................................................................. 22

Figure 2-8: Sample SaveCard Error Response .................................................................................................................. 22

Figure 2-9: Sample DeleteCard Request ............................................................................................................................. 25

Figure 2-10: Sample DeleteCard Response ....................................................................................................................... 26

Figure 2-11: Sample DeleteCard Error Response ............................................................................................................ 26

Figure 2-12: Sample Unenroll Request ................................................................................................................................ 28

Figure 2-13: Sample Unenroll Response ............................................................................................................................. 29

Figure 2-14: Sample Unenroll Error Response.................................................................................................................. 30

Tables

August 2016 Visa Confidential iii

Tables

Table 2-1: Enroll Request Parameters .................................................................................................................................... 3

Table 2-2: Enroll Response Parameters ............................................................................................................................... 12

Table 2-3: Enroll Request Error Codes ................................................................................................................................. 17

Table 2-4: SaveCard Request Parameters .......................................................................................................................... 19

Table 2-5 SaveCard Response Parameters ........................................................................................................................ 21

Table 2-6: SaveCard ErrorCodes ............................................................................................................................................ 23

Table 2-7: DeleteCard Request Parameters ....................................................................................................................... 24

Table 2-8: DeleteCard Response Parameters .................................................................................................................. 25

Table 2-9: DeleteCard Error Codes ....................................................................................................................................... 27

Table 2-10: Unenroll Request Parameters .......................................................................................................................... 28

Table 2-11: Unenroll Response Parameters....................................................................................................................... 29

Table 2-12: Unenroll Error Codes .......................................................................................................................................... 30

Table 2-13: Batch Enrollment Header Record................................................................................................................... 31

Table 2-14: Batch Enrollment Request Data Record ...................................................................................................... 32

Table 2-15: Batch Enrollment Request Trailor Record ................................................................................................... 33

Table 2-16: Batch Enrollment Response Record Format .............................................................................................. 33

Tables

iv Visa Confidential August 2016


August 2016 Visa Confidential 1

About This Guide

Purpose

The Visa Offers Platform Enrollment API provides partners with the following information:

• Technical specification and requirements for developers to implement Visa Offers Platform Web services.

• References to other related publications required during development and implementation of the Visa Offers Platform tools.

Audience

This guide is designed to assist VOP partners in preparing to use the VOP Web Services for enrolling cardholders into a community. This guide is intended for the following individuals:

• Application Developers • System Developers

Requirements

The users of this document must have access to:

• VOP Web Services • Visa Online

Overview

Enrollment API

2 Visa Confidential August 2016

1 Overview

The enrollment API addresses the fundamental task of allowing partners to enroll participants and receive their transaction streams. There are two ways to enroll a participant into Visa Offers Platform:

• Express enrollment • Web service enrollment.

The express enrollment is done via a web form hosted by Visa. This is typically used in environments that do not handle credit cards or cardholder profiles. Express enrollment is also safe to use in a non-PCI compliant environment, since all card information is entered directly into the Visa-hosted web form.

The web service enrollment API (covered in this document) supports basic registration functions (create/enroll user, add/save card, remove/delete card, and unenroll user). This is typically used by partners who already handle cardholder registration and cardholder profile management and who need to register cards into the VOP program.

Programmer’s note:

• This document contains details and samples of the latest VOP WSDL version 7. • ReferenceId is a new field added to most VOP API responses with WSDL 6. This attribute contains a

unique value for each response sent from RTM and can be used for issue management and research. • The “M/O” column header in the Technical Specification stands for “Mandatory/Optional.” • Batch Enrollment is introduced in this document.

2 Technical Specifications

The fundamental task of Visa’s Visa Offers Platform (VOP) Enrollment API is to allow partners to enroll participants and receive relevant information from their transaction activity. The Enrollment Web Services enable partners to create or delete a VOP user profile, as well as add or remove cards from an existing profile.

Visa Offers Platform Web Services authenticate the request message from the client at the transaction level rather than at the login level. After the message is authenticated, the request is authorized in two parts:

• Visa authorizes the sender (your company) to access the Visa Offers Platform Web Service. This level of authorization is verified through a Visa-assigned user ID that is included in the request message header.

• The sender is authorized to access the requested information stored in the Visa Offers Platform Web Service. This level of authorization is based on the partner role definition allocated to a


August 2016 3

company’s Visa-assigned user ID. How a company’s role is defined within the Visa Offers Platform Web Service determines the type of data that are authorized to be requested in the message.

2.1 User and Card Enrollment

Visa’s enrollment web services is the preferred method for transmitting data to Visa for VOP clients who are already PCI compliant or are in the process of becoming compliant.

The Enroll request replaces the CreateEnrollment API in WSDL version 6 and later. This API provides standardized approach to record an enrollee’s personal information, identifying cards and enrollee preferences.

There are 2 ways to register a Card into VOP platform:

• Card details

• Transaction details

A VOP client must include the unique Visa Personal Account Number (PAN) and unique external user id among other user and card attributes when enrolling user by providing card details.

WSDL Version 7 introduces for new capability for enrolling users. Instead of providing a complete PAN a program provider may provide transaction details, for example:

• Transaction date • Amount • Currency • Visa Transaction Id.

The VOP system checks against Visa transaction data in authorized and settlement streams to check for a matching card. If a unique match if found, the VOP system enrolls the card, generates unique id and returns the details in the API response. If a unique match is not found, system returns an appropriate error message.

2.1.1 Enroll Request

For additional information about the individual fields please refer to the Data Dictionary.

Table 2-1: Enroll Request Parameters

Enroll

Fields Data Type M/O

Technical Specifications

Enrollment API


AuthenticationDetails AuthenticationDetails M

BrowserName string O, nillable

CardDetails List<CardInfoRequest> M

If included, DO NOT include TransactionInfo.

CardHolderDetails UserInfoRequest M

CommunityTermsVersion string O, nillable

TransactionInfo TransactionInfo M

If included, DO NOT include CardDetails.

UserAttributes List<UserAttribute> O, nillable

UserPreferences UserPreferences O, nillable

AuthenticationDetails


CommunityCode string M

UserProfileId GUID Do not use. Unavailable at Enroll time.

UserKey string Use only this for an Enroll request.

CardInfoRequest


BillingZipCode string O, nillable

CardId GUID O, nillable

CardNumber string O, nillable

Cvv2 string O, nillable

ExpirationMonth int O, nillable

ExpirationYear int O, nillable

NameOnCard string O, nillable

UserInfoRequest


August 2016 5


ConsumerVerificationCode string O, nillable

ConsumerVerificationValue string O, nillable

Contacts List<ContactInfo> O, nillable

FirstName string O, nillable

LastName string O, nillable

MembershipNumber string O, nillable

ExternalUserId string O, nillable

PromoCode string O, nillable

ReferrerId string O, nillable

IsSmsPreferred bool O, nillable

IsEmailPreferred bool O, nillable

ContactInfo


ContactType NotificationChannelType M, “Sms” or “Email”

ContactValue string M

CountryCode string O, nillable

ContactVerified bool O, nillable

ConfirmationCode string O, nillable

TransactionInfo Data Type M/O

AcquirerBin string O, nillable

AuthCode string O, nillable

CardAcceptorId string O, nillable

CardFirstSix string O, nillable

CardLastFour string O, nillable

MerchantPostalCode string O, nillable

TransactionCurrency string O, nillable

TransactionDateTime dateTime M


Enrollment API


TransactionId string O, nillable The Id can be from an Authorization or Settlement transaction. If included in the request, the TransactionDateTime must also be included. The combination of the Id and TransactionDateTime is sufficient for a request.

TransactionMerchantAmount decimal O, nillable

UserAttribute


Key string O, nillable

Value string (Max) O, nillable

UserPreferences


LanguageId string O, nillable

PreferredCategoryCodes List<CategoryInfo> O, nillable

TimeZoneId string O, nillable

CategoryInfo


Categories List<Category> O, nillable

GroupName string O, nillable

Category


Name string O, nillable

SubGroups List<SubGroup> O, nillable


August 2016 7

SubGroup


Name string O, nillable

Values string O, nillable

Figure 2-1: Sample Enroll Request by Card Details

Sample Enroll Request by CardInfoRequest <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:v7=”http://services.visa.com/realtime/realtimeservice/v7” xmlns:enr=”http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment”> <soapenv:Header/> <soapenv:Body> <v7:Enroll> <v7:request> <enr:AuthenticationDetails> <enr:CommunityCode>SANDBOX</enr:CommunityCode> <enr:UserKey>12011201002</enr:UserKey> </enr:AuthenticationDetails> <enr:BrowserName>IE11</enr:BrowserName> <enr:CardDetails> —!--Zero or more repetitions:--> <enr:CardInfoRequest> <enr:BillingZipCode>94404</enr:BillingZipCode> <enr:CardNumber>4111111111111111</enr:CardNumber> <enr:Cvv2>940</enr:Cvv2> <enr:ExpirationMonth>06</enr:ExpirationMonth> <enr:ExpirationYear>2020</enr:ExpirationYear> <enr:NameOnCard></enr:NameOnCard> </enr:CardInfoRequest> </enr:CardDetails> <enr:CardHolderDetails> <enr:ConsumerVerificationCode>33</enr:ConsumerVerificationCode> <enr:ConsumerVerificationValue>123</enr:ConsumerVerificationValue> <enr:Contacts> —!--Zero or more repetitions:--> <enr:ContactInfo> <enr:ConfirmationCode>speluncis abdidit</enr:ConfirmationCode> <enr:ContactType>Sms</enr:ContactType> <enr:ContactValue>8888888805</enr:ContactValue> <enr:ContactVerified>1</enr:ContactVerified> <enr:CountryCode>01</enr:CountryCode> </enr:ContactInfo> </enr:Contacts> <enr:ExternalUserId>EUIDMOH203</enr:ExternalUserId> <enr:FirstName>John</enr:FirstName> <enr:IsEmailPreferred>true</enr:IsEmailPreferred> <enr:IsSmsPreferred>false</enr:IsSmsPreferred> <enr:LastName>Smith</enr:LastName> <enr:MembershipNumber>123456789</enr:MembershipNumber> <enr:PromoCode>VISAOFFER</enr:PromoCode> <enr:ReferrerId></enr:ReferrerId> </enr:CardHolderDetails>

Enrollment API


Sample Enroll Request by CardInfoRequest <enr:CommunityTermsVersion>1</enr:CommunityTermsVersion> <enr:UserAttributes> —!--Zero or more repetitions:--> <enr:UserAttribute> <enr:Key>MyAttributeKey</enr:Key> <enr:Value>MyAttributeValue</enr:Value> </enr:UserAttribute> </enr:UserAttributes> <enr:UserPreferences> <enr:LanguageId>en-US</enr:LanguageId> <enr:PreferredCategoryCodes> —!--Zero or more repetitions:--> <enr:CategoryInfo> <enr:Categories> <enr:Category> <enr:Name>Food</enr:Name> <enr:SubGroups> —!--Zero or more repetitions:--> <enr:SubGroup> <enr:Name>Min Purchase</enr:Name> <enr:Values>25</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>Max Purchase</enr:Name> <enr:Values>125</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> </enr:Categories> <enr:GroupName>MerchantCategory</enr:GroupName> </enr:CategoryInfo> </enr:PreferredCategoryCodes> <enr:TimeZoneId>PST</enr:TimeZoneId> </enr:UserPreferences> </v7:request> </v7:Enroll> </soapenv:Body> </soapenv:Envelope>

Figure 2-2: Sample Enroll Request by TransactionInfo Using a Transaction Id

Sample Enroll Request by TransactionInfo (Transaction Id) <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:Enroll>  <v7:request> <enr:AuthenticationDetails> <enr:CommunityCode>FMC</enr:CommunityCode> <enr:UserKey>[email protected]</enr:UserKey> </enr:AuthenticationDetails> <enr:BrowserName></enr:BrowserName>

August 2016 9

Sample Enroll Request by TransactionInfo (Transaction Id) <enr:CardHolderDetails> <enr:ConsumerVerificationCode>33</enr:ConsumerVerificationCode> <enr:ConsumerVerificationValue>123</enr:ConsumerVerificationValue> <enr:Contacts>  <enr:ContactInfo> <enr:ConfirmationCode></enr:ConfirmationCode> <enr:ContactType>Sms</enr:ContactType> <enr:ContactValue>5108663070</enr:ContactValue> <enr:ContactVerified>1</enr:ContactVerified> <enr:CountryCode>01</enr:CountryCode> </enr:ContactInfo> <enr:ContactInfo> <enr:ConfirmationCode></enr:ConfirmationCode> <enr:ContactType>Email</enr:ContactType> <enr:ContactValue>[email protected]</enr:ContactValue> <enr:ContactVerified>1</enr:ContactVerified> <enr:CountryCode>01</enr:CountryCode> </enr:ContactInfo> </enr:Contacts>  <enr:ExternalUserId>1481842521756180</enr:ExternalUserId> <enr:FirstName>Jon</enr:FirstName> <enr:IsEmailPreferred>false</enr:IsEmailPreferred> <enr:IsSmsPreferred>true</enr:IsSmsPreferred> <enr:LastName>Smith</enr:LastName> <enr:MembershipNumber></enr:MembershipNumber> <enr:PromoCode>IJKLMNOPQRSTUVWXYZABS</enr:PromoCode> <enr:ReferrerId></enr:ReferrerId> </enr:CardHolderDetails> <enr:CommunityTermsVersion>1</enr:CommunityTermsVersion> <enr:TransactionInfo> <enr:TransactionDateTime>2016-03-05T00:00:00</enr:TransactionDateTime> <enr:TransactionId>386059424940090</enr:TransactionId> </enr:TransactionInfo> <enr:UserAttributes>  <enr:UserAttribute> <enr:Key>color</enr:Key> <enr:Value>blue</enr:Value> </enr:UserAttribute> <enr:UserAttribute> <enr:Key>MyAttributeKey</enr:Key> <enr:Value>MyAttributeValue</enr:Value> </enr:UserAttribute> </enr:UserAttributes>  <enr:UserPreferences> <enr:LanguageId>en-US</enr:LanguageId> <enr:PreferredCategoryCodes> <enr:CategoryInfo> <enr:Categories>  <enr:Category> <enr:Name>Gas</enr:Name> <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category>

Enrollment API


Sample Enroll Request by TransactionInfo (Transaction Id) <enr:Category> <enr:Name>Groceries</enr:Name> <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> <enr:Category> <enr:Name>Travel</enr:Name> <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> </enr:Categories> <enr:GroupName>Mrchcatg</enr:GroupName> </enr:CategoryInfo> </enr:PreferredCategoryCodes> <enr:TimeZoneId>PST</enr:TimeZoneId> </enr:UserPreferences> </v7:request> </v7:Enroll> </soapenv:Body> </soapenv:Envelope>

Figure 2-3: Sample Enroll Request by TransactionInfo Using Transaction Details

Sample Enroll Request by TransactionInfo (Transaction Details) <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:Enroll>  <v7:request> <enr:AuthenticationDetails> <enr:CommunityCode>FMC</enr:CommunityCode> <enr:UserKey>[email protected]</enr:UserKey> </enr:AuthenticationDetails> <enr:BrowserName></enr:BrowserName> <enr:CardHolderDetails> <enr:ConsumerVerificationCode>33</enr:ConsumerVerificationCode> <enr:ConsumerVerificationValue>123</enr:ConsumerVerificationValue> <enr:Contacts>  <enr:ContactInfo> <enr:ConfirmationCode></enr:ConfirmationCode> <enr:ContactType>Sms</enr:ContactType>

August 2016 11

Sample Enroll Request by TransactionInfo (Transaction Details) <enr:ContactValue>5108663070</enr:ContactValue> <enr:ContactVerified>1</enr:ContactVerified> <enr:CountryCode>01</enr:CountryCode> </enr:ContactInfo> <enr:ContactInfo> <enr:ConfirmationCode></enr:ConfirmationCode> <enr:ContactType>Email</enr:ContactType> <enr:ContactValue>[email protected]</enr:ContactValue> <enr:ContactVerified>1</enr:ContactVerified> <enr:CountryCode>01</enr:CountryCode> </enr:ContactInfo> </enr:Contacts>  <enr:ExternalUserId>1481842521756180</enr:ExternalUserId> <enr:FirstName>Jon</enr:FirstName> <enr:IsEmailPreferred>false</enr:IsEmailPreferred> <enr:IsSmsPreferred>true</enr:IsSmsPreferred> <enr:LastName>Smith</enr:LastName> <enr:MembershipNumber></enr:MembershipNumber> <enr:PromoCode>IJKLMNOPQRSTUVWXYZABS</enr:PromoCode> <enr:ReferrerId></enr:ReferrerId> </enr:CardHolderDetails> <enr:CommunityTermsVersion>1</enr:CommunityTermsVersion> <enr:TransactionInfo> <enr:AcquirerBin>314009</enr:AcquirerBin> <enr:AuthCode>024060</enr:AuthCode> <enr:CardAcceptorId>2050T001</enr:CardAcceptorId> <enr:CardFirstSix>427178</enr:CardFirstSix> <enr:CardLastFour>4513</enr:CardLastFour> <enr:TransactionCurrency>840</enr:TransactionCurrency> <enr:TransactionDateTime>2016-05-18T00:00:00</enr:TransactionDateTime> <enr:TransactionMerchantAmount>1050.00</enr:TransactionMerchantAmount> </enr:TransactionInfo> <enr:UserAttributes>  <enr:UserAttribute> <enr:Key>color</enr:Key> <enr:Value>blue</enr:Value> </enr:UserAttribute> <enr:UserAttribute> <enr:Key>MyAttributeKey</enr:Key> <enr:Value>MyAttributeValue</enr:Value> </enr:UserAttribute> </enr:UserAttributes>  <enr:UserPreferences> <enr:LanguageId>en-US</enr:LanguageId> <enr:PreferredCategoryCodes> <enr:CategoryInfo> <enr:Categories>  <enr:Category> <enr:Name>Gas</enr:Name> <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> <enr:Category> <enr:Name>Groceries</enr:Name>


Enrollment API


Sample Enroll Request by TransactionInfo (Transaction Details) <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> <enr:Category> <enr:Name>Travel</enr:Name> <enr:SubGroups> <enr:SubGroup> <enr:Name>MinAmt</enr:Name> <enr:Values>10</enr:Values> </enr:SubGroup> <enr:SubGroup> <enr:Name>MaxAmt</enr:Name> <enr:Values>75</enr:Values> </enr:SubGroup> </enr:SubGroups> </enr:Category> </enr:Categories> <enr:GroupName>Mrchcatg</enr:GroupName> </enr:CategoryInfo> </enr:PreferredCategoryCodes> <enr:TimeZoneId>PST</enr:TimeZoneId> </enr:UserPreferences> </v7:request> </v7:Enroll> </soapenv:Body> </soapenv:Envelope>

2.1.2 Enroll Response

Table 2-2: Enroll Response Parameters

Enroll Response

Fields Data Type

Errors List<Error>

Information List<Message>

ReferenceId Guid

EnrollmentRecord EnrollmentInfoResponse

Error

Fields Data Type


August 2016 13

ErrorCode string

ErrorMessage string

Message

Fields Data Type

Code string

Description string

EnrollmentInfoResponse

Fields Data Type

BrowserName string

CardDetails List<CardInfoResponse>

CardHolderDetails UserInfoResponse

CommunityCode string

CommunityTermsVersion string

UserAttributes List<UserAttribute>

UserKey string

UserPreferences UserPreferences

UserProfileId Guid

UserStatus string

CardInfoResponse

Fields Data Type

CardId GUID

CardLast4 string

CardStatus string

ProductId string

ProductIdDescription string

ProductTypeCategory string

ServiceKey string

UserInfoResponse


Enrollment API


Fields Data Type

ConsumerVerificationCode string

ConsumerVerificationValue string

Contacts List<ContactInfo>

ExternalUserId string

FirstName string

IsEmailPreferred bool

IsSmsPreferred bool

LastName string

MembershipNumber string

PromoCode string

ReferrerId string

UserAttribute

Fields Data Type

Key string

Value string (Max)

UserPreferences

Fields Data Type

LanguageId string See Appendix Error! Reference source not found.

PreferredCategoryCodes List<CategoryInfo>

TimeZoneId string

CategoryInfo

Fields Data Type

Categories List<Category>

GroupName string

Category

Fields Data Type


August 2016 15

Name string

SubGroups List<SubGroup>

SubGroup

Fields Data Type

Name string

Values string

Figure 2-4: Sample Enroll Response

Sample Enroll Response: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> <X-OPNET-Transaction-Trace xmlns="http://opnet.com">6df7c04b-0d6b-4ce6-a458-15efa72be150-16668-3462</X-OPNET-Transaction-Trace> </s:Header> <s:Body> <EnrollResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <EnrollResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <Errors i:nil="true" xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">fd379638-0382-4f89-9562-05ee0a644c4d</ReferenceId> <a:EnrollmentRecord> <a:BrowserName>IE11</a:BrowserName> <a:CardDetails> <a:CardInfoResponse> <a:CardId>bfc33c1d-d4ef-e111-8d48-001a4bcdeef4</a:CardId> <a:CardLast4>1111</a:CardLast4> <a:CardStatus>New</a:CardStatus> <a:ProductId i:nil="true"/> <a:ProductIdDescription i:nil="true"/> <a:ProductTypeCategory i:nil="true"/> </a:CardInfoResponse> </a:CardDetails> <a:CardHolderDetails> <a:Contacts> <a:ContactInfo> <a:ConfirmationCode>speluncis abdidit</a:ConfirmationCode> <a:ContactType>Sms</a:ContactType> <a:ContactValue>8888888805</a:ContactValue> <a:ContactVerified>true</a:ContactVerified> <a:CountryCode>1</a:CountryCode> </a:ContactInfo> </a:Contacts> <a:EnrolledDate>2016-04-25T19:28:54.347</a:EnrolledDate> <a:ExternalUserId>EUIDMOH203</a:ExternalUserId> <a:FirstName>John</a:FirstName> <a:IsDeleted>false</a:IsDeleted> <a:IsEmailPreferred>true</a:IsEmailPreferred> <a:IsSmsPreferred>false</a:IsSmsPreferred> <a:LastName>Smith</a:LastName>


Enrollment API


Sample Enroll Response: Success <a:MembershipNumber>123456789</a:MembershipNumber> <a:PromoCode>VISAOFFER</a:PromoCode> <a:ReferrerId i:nil="true"/> <a:VisaOptIn>false</a:VisaOptIn> </a:CardHolderDetails> <a:CommunityCode>GAP</a:CommunityCode> <a:CommunityTermsVersion>1</a:CommunityTermsVersion> <a:UserAttributes> <a:UserAttribute> <a:Key>MyAttributeKey</a:Key> <a:Value>MyAttributeValue</a:Value> </a:UserAttribute> </a:UserAttributes> <a:UserKey>12011201002</a:UserKey> <a:UserPreferences> <a:LanguageId>en-US</a:LanguageId> <a:PreferredCategoryCodes> <a:CategoryInfo> <a:Categories> <a:Category> <a:Name>Food</a:Name> <a:SubGroups> <a:SubGroup> <a:Name>Min Purchase</a:Name> <a:Values>25</a:Values> </a:SubGroup> <a:SubGroup> <a:Name>Max Purchase</a:Name> <a:Values>125</a:Values> </a:SubGroup> </a:SubGroups> </a:Category> </a:Categories> <a:GroupName>MerchantCategory</a:GroupName> </a:CategoryInfo> </a:PreferredCategoryCodes> <a:TimeZoneId>Pacific Standard Time</a:TimeZoneId> </a:UserPreferences> <a:UserProfileId>ebe9228c-9a1e-4529-87db-d0032abebe27</a:UserProfileId> <a:UserStatus>Active</a:UserStatus> </a:EnrollmentRecord> <a:Success>true</a:Success> </EnrollResult> </EnrollResponse> </s:Body>

</s:Envelope>

Figure 2-5: Sample Enroll Error Response

Sample Enroll Response: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <EnrollResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <EnrollResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Error> <ErrorCode>RTMENRE0025</ErrorCode> <ErrorMessage>The user key provided is already in use</ErrorMessage> </Error> </Errors> <Information


August 2016 17

Sample Enroll Response: Error xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">79af1e1a-df09-4874-ad07-d1c5c2fe36ff</ReferenceId> <a:EnrollmentRecord i:nil="true"/> <a:Success>false</a:Success> </EnrollResult> </EnrollResponse> </s:Body> </s:Envelope>

2.1.3 Enroll Errors

Table 2-3: Enroll Request Error Codes

Error Code Error Message

1000 Authentication Exception

1010 Unauthorized Exception

2000 Invalid Argument Exception

3000 SQL Exception

4000 Timeout Exception

5000 Internal Server Error

6000 External Provider Exception

7000 Not supported exception

RTMENRE0003 Invalid Mobile Country Code.

RTMENRE0005 Invalid User Attribute.

RTMENRE0008 Invalid Email Address format.

RTMENRE0011 Invalid MobileNumber.

RTMENRE0015 Invalid Card expiration date.

RTMENRE0016 Invalid EUID.

RTMENRE0017 Invalid Language Id.

RTMENRE0019 Invalid Promo Code (Usually because of special characters or spaces)

RTMENRE0021 Invalid user status. (Usually, user is already enrolled)

RTMENRE0022 Invalid UserKey.

RTMENRE0023 Invalid Community T&C version.


Enrollment API


RTMENRE0025 The user key provided is already in use.

RTMENRE0028 Enrollment Disabled

RTMENRE0032 Maximum enrolled cards reached

RTMENRE0035 Invalid Billing Zip.

RTMENRE0039 Invalid Last Name.

RTMENRE0042 Maximum PAN usage reached.

RTMENRE0044 Invalid Card number.

RTMENRE0049 Both UserKey and User Profile Id should not be provided together

RTMENRE0052 Invalid First Name.

RTMENRE0053 Invalid User Attribute.

RTMENRE0054 Empty card details.

RTMENRE0055 Category is invalid.

RTMENRE0056 Invalid category group name

RTMENRE0057 Invalid category group value.

RTMENRE0058 Category sub group is invalid.

RTMENRE0059 Invalid category sub group name.

RTMENRE0060 Invalid category sub group value.

RTMENRE0061 Category sub group is not allowed.

RTMENRE0071 Card and Transaction details are null.

RTMENRE0072 Card and Transaction can not exist in request.

RTMENRE0075 TransactionInfo provided is insufficient for search.

RTMENRE0077 No card returned from search.

RTMENRE0078 Search returned multiple cards.

RTMENRE0080 Invalid CardLastFour in TransactionDetail.

RTMENRE0081 Invalid CardFirstSix in TransactionDetail.

RTMENRE0082 Invalid TransactionId in TransactionDetail.

RTMENRE0083 Invalid TransactionCurrency in TransactionDetail.

RTMENRE0084 Invalid MerchantPostalCode in TransactionDetail.

RTMENRE0085 AcquirerBin in TransactionDetail.


August 2016 19

RTMENRE0086 Invalid AuthCode in TransactionDetail.

RTMENRE0087 Invalid CardAcceptorId in TransactionDetail.

RTMENRE0088 Search CMLS transaction detail throttle exceeded.

RTMENRE0089 TransactionDate exceeded maximum transaction date span.

2.2 Add Card to Existing Profile

2.2.1 SaveCard Request

The SaveCard web service call adds a card number into an existing user’s profile. Please review your implementation documents for the maximum number of cards that can be added to a profile.

Please note, that calling SaveCard with a card number that already exists for this cardholder will update card details, and will not result in error. However, calling SaveCard with a card number that already exists on some other user profile will result in “Maximum_PAN_Usage_Reached” error.


Table 2-4: SaveCard Request Parameters

SaveCard Request



CardInfoRequest CardInfoRequest M




UserProfileId GUID O Use one of UserProfileId or UserKey

UserKey string O, nillable Use one of UserProfileId or UserKey

CardInfoRequest

Enrollment API



BillingZipCode string O, nillable

CardId GUID O, nillable

CardNumber string O, nillable

Cvv2 string O, nillable

ExpirationMonth int O, nillable

ExpirationYear int O, nillable

NameOnCard string O, nillable

Figure 2-6: Sample SaveCard Request

Sample SaveCard Request: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:SaveCard>  <v7:request> <enr:AuthenticationDetails> <enr:CommunityCode>SANDBOX</enr:CommunityCode>   <enr:UserKey>test</enr:UserKey> </enr:AuthenticationDetails>  <enr:CardInfoRequest>  <enr:BillingZipCode>94404</enr:BillingZipCode>  <enr:CardNumber>4444499991111666</enr:CardNumber>  <enr:Cvv2/>  <enr:ExpirationMonth>12</enr:ExpirationMonth>  <enr:ExpirationYear>2100</enr:ExpirationYear>  <enr:NameOnCard/> </enr:CardInfoRequest> </v7:request> </v7:SaveCard> </soapenv:Body> </soapenv:Envelope>

2.2.2 SaveCard Response


August 2016 21

Table 2-5 SaveCard Response Parameters

SaveCard Response

Fields Data Type

Errors List<Error>


ReferenceId GUID

CardInfoResponse CardInfoResponse

Success bool

CardInfoResponse

Fields Data Type

CardId GUID

CardLast4 string

CardStatus ‘New’ value

ProductId string

ProductIdDescription string

ProductTypeCategory string

Error

Fields Data Type

ErrorCode string

ErrorMessage string

Message

Fields Data Type

Code string

Description string


Enrollment API


Figure 2-7: Sample SaveCard Response

Sample SaveCardResponse: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> <X-OPNET-Transaction-Trace xmlns="http://opnet.com">0375fc2e-0903-44ee-872a-64000a97f0f4-30344-79</X-OPNET-Transaction-Trace> </s:Header> <s:Body> <SaveCardResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <SaveCardResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">e5c4e6e4-cc40-4d24-baed-ecd2d8e181f9</ReferenceId> <a:CardInfoResponse> <a:CardId>8c99f0fa-2e07-e611-8092-005056b225d2</a:CardId> <a:CardLast4>1666</a:CardLast4> <a:CardStatus>New</a:CardStatus> <a:ProductId>F</a:ProductId> <a:ProductIdDescription>Visa Classic</a:ProductIdDescription> <a:ProductTypeCategory>Credit</a:ProductTypeCategory> </a:CardInfoResponse> <a:Success>true</a:Success> </SaveCardResult> </SaveCardResponse> </s:Body> </s:Envelope>

Figure 2-8: Sample SaveCard Error Response

Sample SaveCardResponse: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <SaveCardResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <SaveCardResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Error> <ErrorCode>RTMENRE0044</ErrorCode> <ErrorMessage>Invalid Card number.</ErrorMessage> </Error> </Errors> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">ef41ebee-16a3-450e-8122-fde9fec60ad2</ReferenceId> <a:CardInfoResponse i:nil="true"/> <a:Success>false</a:Success> </SaveCardResult> </SaveCardResponse> </s:Body> </s:Envelope>


August 2016 23

2.2.3 SaveCard Errors

Below is a complete list of the error codes that can be returned after a web service user has successfully passed HTTP and SOAP WSS security validation.

Table 2-6: SaveCard ErrorCodes





3000 SQL Exception





RTMENRE0001 AVS check failed.

RTMENRE0006 Invalid Account Number

RTMENRE0014 Card Already Expired.

RTMENRE0015 Invalid Card expiration date.

RTMENRE0020 Invalid Security code.


RTMENRE0026 Enroll User not found

RTMENRE0027 Invalid Community code.


RTMENRE0029 Enrollment record is null.

RTMENRE0030 Bad Card throttle Exceeded.

RTMENRE0032 Max card limit reached.


RTMENRE0036 Invalid Community Code.

RTMENRE0037 Invalid Enrollment Id.

RTMENRE0038 Invalid last four digit of card number.


Enrollment API



RTMENRE0041 Userkey and Identity Provider combination is invalid

RTMENRE0042 Maximum PAN usage reached.

RTMENRE0043 Authentication Record is null.


RTMENRE0047 Mod 10 check failed.

RTMENRE0048 Null request.

2.3 Remove Card from Existing Profile

2.3.1 DeleteCard Request

The DeleteCard web service call removes a card number from an existing user’s profile. The request takes an unencrypted 16-digit card account number or 36 character CardId provided in End Point Messages (EPMs) or in responses to Enroll and SaveCard web service calls as an input parameter.


Table 2-7: DeleteCard Request Parameters

DeleteCard Request



CardNumber string Either CardNumber or CardId

CardId GUID Either CardNumber or CardId




UserProfileId GUID Either UserProfileId or UserKey

August 2016 25

UserKey string Either UserProfileId or UserKey

Figure 2-9: Sample DeleteCard Request

Sample DeleteCard Request: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:DeleteCard>  <v7:deleteCardRequest> <enr:AuthenticationDetails> <enr:CommunityCode>SANDBOX</enr:CommunityCode>   <enr:UserKey>test</enr:UserKey> </enr:AuthenticationDetails>  <enr:CardNumber>4444555566667777</enr:CardNumber> </v7:deleteCardRequest> </v7:DeleteCard> </soapenv:Body> </soapenv:Envelope>

2.3.2 DeleteCard Response


Table 2-8: DeleteCard Response Parameters

DeleteCard Response

Fields Data Type

Errors List<Error>


ReferenceId GUID

Success bool

Error

Fields Data Type

ErrorCode string

ErrorMessage string


Enrollment API


Message

Fields Data Type

Code string

Description string

Figure 2-10: Sample DeleteCard Response

Sample DeleteCardResponse: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <DeleteCardResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <DeleteCardResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Message> <Code>Information Code</Code> <Description>Information Description</Description> </Message> </Information> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">908c1b96-6ccc-47ce-b235-acf5e2276e62</ReferenceId> <a:Success>true</a:Success> </DeleteCardResult> </DeleteCardResponse> </s:Body> </s:Envelope>

Figure 2-11: Sample DeleteCard Error Response

Sample DeleteCardResponse: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <DeleteCardResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <DeleteCardResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Error> <ErrorCode>RTMENRE0044</ErrorCode> <ErrorMessage>Invalid Card number.</ErrorMessage> </Error> </Errors> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">0088d8c8-baad-46a5-9b01-e59ca1096a2a</ReferenceId> <a:Success>false</a:Success> </DeleteCardResult> </DeleteCardResponse>


August 2016 27

Sample DeleteCardResponse: Error </s:Body> </s:Envelope>

2.3.3 DeleteCard Errors

Table 2-9: DeleteCard Error Codes





3000 SQL Exception





RTMENRE0002 Reached Minimum Number of Cards.




RTMENRE0030 Bad Card throttle Exceeded.


RTMENRE0036 Invalid Community Code.

RTMENRE0037 Invalid Enrollment Id.

RTMENRE0038 Invalid last four digit of card number.


RTMENRE0043 Authentication Record is null.


RTMENRE0048 Null request.

Enrollment API


2.4 Unenroll - Remove User Profile

2.4.1 Unenroll Request

Enrollees have the option of un-enrolling from a community. Should he or she select this option, a partner must use this Web Service to Un-enroll a participant. All the cards associated with the user will be marked inactive as well.


Table 2-10: Unenroll Request Parameters

Unenroll Request


AuthenticationDetails AuthenticationDetails O




UserProfileId GUID Either UserProfileId or UserKey

UserKey string Either UserProfileId or UserKey

Figure 2-12: Sample Unenroll Request

Sample Unenroll Request: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:Unenroll>  <v7:request> <enr:AuthenticationDetails> <enr:CommunityCode>SANDBOX</enr:CommunityCode>  <enr:UserProfileId>ca5d4409-574e-e111-ba3b-001a4ba980c6</enr:UserProfileId> </enr:AuthenticationDetails> </v7:request> </v7:Unenroll> </soapenv:Body> </soapenv:Envelope>


August 2016 29

2.4.2 Unenroll Response

Table 2-11: Unenroll Response Parameters

Unenroll Response

Fields Data Type

Errors List<Error>


ReferenceId GUID

Success bool

Error

Fields Data Type

ErrorCode string

ErrorMessage string

Information

Fields Data Type

Code string

Description string

Figure 2-13: Sample Unenroll Response

Sample Unenroll Response: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <UnenrollResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <UnenrollResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors i:nil="true" xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Message> <Code>Information Code</Code> <Description>Information Description</Description> </Message> </Information> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">2ce6dbad-b6fe-4fa4-94ff-2121290b6e18</ReferenceId> <a:Success>true</a:Success> </UnenrollResult> </UnenrollResponse>


Enrollment API


Sample Unenroll Response: Success </s:Body> </s:Envelope>

Figure 2-14: Sample Unenroll Error Response

Sample Unenroll Response: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <UnenrollResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <UnenrollResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <Errors xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <Error> <ErrorCode>RTMENRE0026</ErrorCode> <ErrorMessage>Enroll User not found</ErrorMessage> </Error> </Errors> <Information xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"/> <ReferenceId xmlns="http://services.visa.com/realtime/realtimeservice/datacontracts/v7">3efddd97-3e27-4e0d-8f1e-7e129415250a</ReferenceId> <a:Success>false</a:Success> </UnenrollResult> </UnenrollResponse> </s:Body> </s:Envelope>

2.4.3 Unenroll Errors

Table 2-12: Unenroll Error Codes





3000 SQL Exception





August 2016 31



RTMENRE0049 Both UserKey and User Profile Id should not be provided together

RTMENRE0050 Invalid user status

2.5 Batch Enrollment

Clients may choose to maintain users’ enrollment records by means of VOP’s batch enrollment service. Partners may submit a comma delimited file via an SFTP connection. SFTP connectivity details are described in the Visa Offers Platform Implementation Guide. The specific details for your connection will be worked out with your Visa Implementation Manager.

The first record is a header. Subsequent records contain details for individual enrollments.

All fields are required, although some may be blank. The Mandatory/Optional codes indicate whether the field’s content is mandatory or optional.

Table 2-13: Batch Enrollment Header Record

Field Number

Data Element Sample Data Description

0 Record Type 00 M Required entry is “00”

1 Record SubType 00 M Required entry is “00”

2 Sender/Source ID SANDBOX M Denotes the entity sending the file. Must be a valid Community Code as defined in an RTM program.

3 Receiver/ Destination ID

VISA M Required entry. Denotes the intended recipient of the file. Must be VISA.

4 File Description ENROLLMENT REQUEST

M Identifies the type of batch request

5 File Create Date 6/1/2015 M The date on which the file was created by the Sender.

6 File Control Number

00 O A two-digit sequence value used in case multiple files are sent by the same Sender/Source with the same Promotion Type/Code and Content Start/End dates. Default value is 00; the value is incremented to 01, 02, etc. for each additional file.


Enrollment API


7 File Format Version 1 M Indicates the format version of the file.

8 Filler x

9 Test File Indicator T M Indicates whether the file contains production or test data. Valid values:

P = Production

T = Test

10 Content Start Date 5/1/2015 O Start date of the period for the data stored within the file.

11 Content End Date 5/31/2015 O End date of the period for the data stored within the file. If the file contents are for a single day, this value is equal to the Content Start Date.

12 Filler Blank

13 Filler Blank

14 File Type Indicator I

16 File Unique Text A0000000001 A unique identifier to identify the file. User specified. Whatever value specified will be populated in the corresponding response file.

The subsequent records specify changes and additions for individual enrollees.

Table 2-14: Batch Enrollment Request Data Record

Record Number

Field Data Type M/O Description

0 RequestType Letters: E, S, D, U M E: Enroll

S: Add a card to an existing enrollment

D: Delete a card from an enrollment

U: Unenroll

1 CommunityCode String M Identifies the community for which the data applies.

2 UserKey String M Client defined unique identifier for the enrolled user. Uniquely identifies an enrollment within a community.

3 CardNumber 16 digit mod 10 number

M for E, S, D

O for U

4 BillingZipCode String M, nillable M for S, E, if AVS is on

5 Cvv2 3 digits M, nillable

6 ExpirationMonth Numeric integer M, nillable Number between 01 & 12


August 2016 33

M for S, E, if AVS is on

7 ExpirationYear 4 digits M, nillable M for S, E, if AVS is on

8 FirstName String M, nillable

9 LastName String M, nillable

10 CountryCode Numeric string M, nillable Integer from the list of country codes.

11 PhoneNumber Numeric string M, nillable M if marked mandatory in community settings

12 Email String M, nillable M if marked mandatory in community settings

The subsequent records specify changes and additions for individual enrollees.

Table 2-15: Batch Enrollment Request Trailor Record

Field Number

Data Element Sample Data Description

0 Record Type 99 M Required entry is “00”

1 Record SubType 99 M Required entry is “00”

2 Record Count - File Level

15 M Denotes the number of records in the file. If the total number of records in the file does not match record count, the file processing will fail.

3 Filler Blank Reserved for future use

The response will consist of a header record followed by a record for each request line.

The response header record will be the one sent with the request.

The header record has 15 fields. The subsequent records have 14 fields.

Table 2-16: Batch Enrollment Response Record Format

Request Values Examples

0 Request Type E for Enroll

S for Save

D for Delete

U for Unenroll

1 Success TRUE

FALSE


Enrollment API


2 Error Code Any RTM error code listed in the error codes for Enroll, SaveCard, DeleteCard and Unenroll APIs

RTMENRE0000

3 Error Message Message associated with code.

Card already enrolled

4 Community Code SANDBOX

5 UserKey Unique identifier for the enrollee defined by VOP client

1234567890

6 UserProfileId Value returned by VOP that uniquely identifies an enrollee.

15c922db-57c2-4078-9027-82847bc0f251

7 CardId Value returned by VOP that uniquely identifies a Personal Account Number (PAN)

20c922db-57c2-4078-5555-82847bc0f251

8 CardLast4 Last four digits of a PAN. 5771

9 ReferenceId Unique Id generated by VOP for each API response

60c922db-57c2-5566-5555-82847bc0f231


August 2016 35

A Data Dictionary

Data types defined for Visa APIs have been standardized for field length. Refer to the table below for Data Types and their corresponding field lengths.

Data Type Field Length

bool 5

DateTime 50

decimal 10 (max value 2147483647)

GUID 36 example: ca5d4409-574e-e111-ba3b-001a4ba980c6

Int 10 (max value 2147483647)

List<<…..>> ** system max **

MonetaryAmount Money Data type

String 255

String(Max) ** system max **


Enrollment API


B Fields

Fields Description

AuthenticationRecord There are two types. Which one is appropriate for a given partner depends on the initial setup configuration. A client may choose from the following combinations:

• UserProfileId

• UserKey

UserProfileId is Visa supplied and returned after a user is enrolled. It is guaranteed to be unique throughout VOP.

UserKey may be either a telephone number, email address or a unique id assigned by the client. In this case the client is responsible for maintaining uniqueness. If the client chooses to manage users by means of telephone numbers, the country code must be included. In the USA the area code is 1. A user enrolled with a ten digit telephone number cannot be unenrolled with a UserKey.

BillingZipCode Billing Zip code for the card account number

BrowserName A descriptive name of the user’s browser

CardDetails A list of CardInfoResponse objects. The Community may set a limit on the number of Cards each Consumer may enroll, which must be greater than 0, maximum 5.

CardHolderDetails An instance of the UserInfoResponse class.

CardId The database identifier of the service record for the PAN. Returned by VOP after a successful Enroll. Once obtained it may be used instead of the CardNumber.

CardNumber The user’s card number that is associated with the enrollment. Only numeric characters. The same CardNumber can only be enrolled under the same community once. If the Partner attempts to enroll an already enrolled PAN, an error response will be provided.

CategoryCode Predefined value related to the community and offer

CommunityCode Visa will provide the Community Code for partner to pass.

CommunityTermsVersion The latest version of the community terms and conditions accepted by the user

ConfirmationCode Returned by VOP after a successful Enrollment. For SMS contacts it will be the three character code that VOP has sent to the enrollee.

Contacts List of ContactInfo objects.

ContactType Instance of NotificationChannelType. The type of contact, specifically “Sms” for text or “Email” for email,


August 2016 37

ContactValue The contact details for the contact (for example, if ContactType is Email, then the contact value is the enrolled user’s email address).

ContactVerified Denotes if the contact information has been verified. Specifically, the user has responded to a message sent via the contact channel.

CountryCode The country identifying information for the contact. See Appendix Error! Reference source not found.-Error! Reference source not found..

Cvv2 The Cvv 2 number on the back of the card. Three digits.

Email Email ContactType should have Email Address in ContactValue.

EnrolledDate Date and time of enrollment in GMT format, for example, 2015-04-20T00:52:18.203.

ErrorCode A unique code to describe the type of validation error occurred

ErrorMessage A description of an error that occurred during the request

ExpirationMonth The Month the card expires MM. Month must be between 01 and 12 inclusive.

ExpirationYear The Year the card expires YYYY. Year cannot be in the past.

ExternalUserId An alphanumeric user identifier of arbitrary length supplied by a partner that identifies a user within his or her application. Supplied as part of an Enroll request and returned as part of an Enroll response.

FirstName First name of the enrolled user.

GroupCode Predefined value related to the community and offer.

InformationCode Not used for enrollment APIs.

InformationMessage Not used for enrollment APIs.

IsDeleted Value can be either “true” or “false.”

IsEmailPreferred True or False only

IsSmsPreferred Value can be either “true” or “false.”

LanguageId The unique identifier used to describe what language the user speaks. For example, “en-US.” See Appendix Error! Reference source not found. - Error! Reference source not found..

LastName Last name of the enrolled user.

MembershipNumber A special identification number internal to the community (depends on community setting)

MobilePhoneCountryCode The enrolled user’s cell phone country code

MobilePhoneNumber The enrolled user’s cell phone number

NameOnCard Name as it appears on the Visa card.


Enrollment API


PreferredCategoryCodes List of preferred codes as strings.

PromoCode Promotional code associated with the enrollment of the user. VOP sets the PromoCode to upper case upon receipt. Alphanumeric. No special characters.

ReferrerId To be deprecated.

SMS Member of an enumeration used to describe different notification channels. SMS ContactType should have the corresponding mobile number in ContactValue.

TimeZoneId Unique identifier for the user’s time zone, for example, PST, CST, MST, EST…

UserAttributes Collection of UserAttribute objects

UserKey A unique identifier provided by a partner, typically either an email address or a mobile telephone number. Which one is required is a profile configuration item for a community. An AuthenticationRecord containing a CommunityCode and a UserKey is mandatory for Enroll requests. When a mobile telephone number is required for a community the telephone number must contain a country code. In the United States a mobile number must start with a “1” and be 11 digits long. An AuthenticationRecord must contain either a UserProfileId or a UserKey, but not both. May be used in SaveCard, DeleteCard and Unenroll requests.

UserPreferences Collection of UserPreference objects.

UserProfileId Unique enrollment record identifier or user ID generated by Visa as a part of an Enroll response. Optional for Enroll requests. An AuthenticationRecord must contain either a UserProfileId or a UserKey, but not both. May be used in SaveCard, DeleteCard and Unenroll requests.

UserStatus Field must have the static value “Active” in Enroll requests.


August 2016 39

visa offers platform - visa developer center€¢ technical specification and requirements for...

Documents