Professional Documents
Culture Documents
Enrollment API
August 2016
Visa Confidential
Important Information on Confidentiality and Copyright
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
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
Tables
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
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.
Programmers 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 Visas 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
companys Visa-assigned user ID. How a companys role is defined within the Visa Offers Platform
Web Service determines the type of data that are authorized to be requested in the message.
Visas 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 enrollees personal information, identifying cards and enrollee
preferences.
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.
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
August 2016 3
Technical Specifications
Enrollment API
AuthenticationDetails AuthenticationDetails M
AuthenticationDetails
CommunityCode string M
UserProfileId GUID Do not use. Unavailable at Enroll time.
CardInfoRequest
UserInfoRequest
ContactInfo
ContactValue string M
CountryCode string O, nillable
ContactVerified bool O, nillable
ConfirmationCode string O, nillable
August 2016 5
Technical Specifications
Enrollment API
UserAttribute
UserPreferences
CategoryInfo
Category
SubGroup
August 2016 7
Technical Specifications
Enrollment API
August 2016 9
Technical Specifications
Enrollment API
August 2016 11
Technical Specifications
Enrollment API
Enroll Response
Fields Data Type
Errors List<Error>
Information List<Message>
ReferenceId Guid
EnrollmentRecord EnrollmentInfoResponse
Error
Fields Data Type
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
August 2016 13
Technical Specifications
Enrollment API
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
Name string
SubGroups List<SubGroup>
SubGroup
Fields Data Type
Name string
Values string
August 2016 15
Technical Specifications
Enrollment API
August 2016 17
Technical Specifications
Enrollment API
The SaveCard web service call adds a card number into an existing users 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.
For additional information about the individual fields please refer to the Data Dictionary.
Table 2-4: SaveCard Request Parameters
SaveCard Request
Fields Data Type M/O
AuthenticationDetails AuthenticationDetails M
CardInfoRequest CardInfoRequest M
AuthenticationDetails
Fields Data Type M/O
CommunityCode string M
UserProfileId GUID O Use one of UserProfileId or UserKey
UserKey string O, nillable Use one of UserProfileId or UserKey
CardInfoRequest
August 2016 19
Technical Specifications
Enrollment API
SaveCard Response
Fields Data Type
Errors List<Error>
Information List<Message>
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
August 2016 21
Technical Specifications
Enrollment API
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
August 2016 23
Technical Specifications
Enrollment API
The DeleteCard web service call removes a card number from an existing users 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.
For additional information about the individual fields please refer to the Data Dictionary.
Table 2-7: DeleteCard Request Parameters
DeleteCard Request
Fields Data Type M/O
AuthenticationDetails AuthenticationDetails M
AuthenticationDetails
Fields Data Type M/O
CommunityCode string M
UserProfileId GUID Either UserProfileId or UserKey
For additional information about the individual fields please refer to the Data Dictionary.
Table 2-8: DeleteCard Response Parameters
DeleteCard Response
Fields Data Type
Errors List<Error>
Information List<Message>
ReferenceId GUID
Success bool
Error
Fields Data Type
ErrorCode string
ErrorMessage string
August 2016 25
Technical Specifications
Enrollment API
Message
Fields Data Type
Code string
Description string
August 2016 27
Technical Specifications
Enrollment API
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.
For additional information about the individual fields please refer to the Data Dictionary.
Table 2-10: Unenroll Request Parameters
Unenroll Request
Fields Data Type M/O
AuthenticationDetails AuthenticationDetails O
AuthenticationDetails
Fields Data Type M/O
CommunityCode string M
UserProfileId GUID Either UserProfileId or UserKey
UserKey string Either UserProfileId or UserKey
Unenroll Response
Fields Data Type
Errors List<Error>
Information List<Message>
ReferenceId GUID
Success bool
Error
Fields Data Type
ErrorCode string
ErrorMessage string
Information
Fields Data Type
Code string
Description string
August 2016 29
Technical Specifications
Enrollment API
Clients may choose to maintain users enrollment records by means of VOPs 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 fields content is mandatory or optional.
Table 2-13: Batch Enrollment Header Record
August 2016 31
Technical Specifications
Enrollment API
The subsequent records specify changes and additions for individual enrollees.
Table 2-14: Batch Enrollment Request Data Record
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
The subsequent records specify changes and additions for individual enrollees.
Table 2-15: Batch Enrollment Request Trailor Record
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.
August 2016 33
Technical Specifications
Enrollment API
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.
August 2016 35
Technical Specifications
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
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 users 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.
ContactValue The contact details for the contact (for example, if ContactType is Email, then the
contact value is the enrolled users 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.
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
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.
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.
August 2016 37
Technical Specifications
Enrollment API
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.
August 2016 39