You are on page 1of 45

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

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

August 2016 Visa Confidential i


Figures

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

ii Visa Confidential August 2016


Tables

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

August 2016 Visa Confidential iii


Tables

iv Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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

August 2016 Visa Confidential 1


Overview
Enrollment API

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

2 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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.

2.1 User and Card Enrollment

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.

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

August 2016 3
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

Fields Data Type M/O

CommunityCode string M
UserProfileId GUID Do not use. Unavailable at Enroll time.

UserKey string Use only this for an Enroll request.

CardInfoRequest

Fields Data Type M/O

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

4 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

Fields Data Type M/O

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

Fields Data Type M/O

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

August 2016 5
Technical Specifications
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

Fields Data Type M/O

Key string O, nillable


Value string (Max) O, nillable

UserPreferences

Fields Data Type M/O

LanguageId string O, nillable


PreferredCategoryCodes List<CategoryInfo> O, nillable

TimeZoneId string O, nillable

CategoryInfo

Fields Data Type M/O

Categories List<Category> O, nillable

GroupName string O, nillable

Category

Fields Data Type M/O

Name string O, nillable

SubGroups List<SubGroup> O, nillable

6 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

SubGroup

Fields Data Type M/O

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>

August 2016 7
Technical Specifications
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>
<!--Optional:-->
<v7:request>
<enr:AuthenticationDetails>
<enr:CommunityCode>FMC</enr:CommunityCode>
<enr:UserKey>a56727@visa.com</enr:UserKey>
</enr:AuthenticationDetails>
<enr:BrowserName></enr:BrowserName>

8 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

Sample Enroll Request by TransactionInfo (Transaction Id)


<enr:CardHolderDetails>
<enr:ConsumerVerificationCode>33</enr:ConsumerVerificationCode>
<enr:ConsumerVerificationValue>123</enr:ConsumerVerificationValue>
<enr:Contacts>
<!--Zero or more repetitions:-->
<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>johnsmith195@test.com</enr:ContactValue>
<enr:ContactVerified>1</enr:ContactVerified>
<enr:CountryCode>01</enr:CountryCode>
</enr:ContactInfo>
</enr:Contacts>
<!--Optional:-->
<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>
<!--Zero or more repetitions:-->
<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>
<!--Optional:-->
<enr:UserPreferences>
<enr:LanguageId>en-US</enr:LanguageId>
<enr:PreferredCategoryCodes>
<enr:CategoryInfo>
<enr:Categories>
<!--Zero or more repetitions:-->
<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>

August 2016 9
Technical Specifications
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>
<!--Optional:-->
<v7:request>
<enr:AuthenticationDetails>
<enr:CommunityCode>FMC</enr:CommunityCode>
<enr:UserKey>a56727@visa.com</enr:UserKey>
</enr:AuthenticationDetails>
<enr:BrowserName></enr:BrowserName>
<enr:CardHolderDetails>
<enr:ConsumerVerificationCode>33</enr:ConsumerVerificationCode>
<enr:ConsumerVerificationValue>123</enr:ConsumerVerificationValue>
<enr:Contacts>
<!--Zero or more repetitions:-->
<enr:ContactInfo>
<enr:ConfirmationCode></enr:ConfirmationCode>
<enr:ContactType>Sms</enr:ContactType>

10 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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>johnsmith195@test.com</enr:ContactValue>
<enr:ContactVerified>1</enr:ContactVerified>
<enr:CountryCode>01</enr:CountryCode>
</enr:ContactInfo>
</enr:Contacts>
<!--Optional:-->
<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>
<!--Zero or more repetitions:-->
<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>
<!--Optional:-->
<enr:UserPreferences>
<enr:LanguageId>en-US</enr:LanguageId>
<enr:PreferredCategoryCodes>
<enr:CategoryInfo>
<enr:Categories>
<!--Zero or more repetitions:-->
<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>

August 2016 11
Technical Specifications
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

12 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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

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

14 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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>

August 2016 15
Technical Specifications
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

16 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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.

August 2016 17
Technical Specifications
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.

18 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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 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

Fields Data Type M/O


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>
<!--Optional:-->
<v7:request>
<enr:AuthenticationDetails>
<enr:CommunityCode>SANDBOX</enr:CommunityCode>
<!--Either UserKey or UserProfileId should be provided. Both are Mutually Exclusive-->
<!--Optional:-->
<enr:UserKey>test</enr:UserKey>
</enr:AuthenticationDetails>
<!--Optional:-->
<enr:CardInfoRequest>
<!--Optional:-->
<enr:BillingZipCode>94404</enr:BillingZipCode>
<!--Optional:-->
<enr:CardNumber>4444499991111666</enr:CardNumber>
<!--Optional:-->
<enr:Cvv2/>
<!--Optional:-->
<enr:ExpirationMonth>12</enr:ExpirationMonth>
<!--Optional:-->
<enr:ExpirationYear>2100</enr:ExpirationYear>
<!--Optional:-->
<enr:NameOnCard/>
</enr:CardInfoRequest>
</v7:request>
</v7:SaveCard>
</soapenv:Body>
</soapenv:Envelope>

2.2.2 SaveCard Response

20 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

Table 2-5 SaveCard Response Parameters

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

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>

22 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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

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
RTMENRE0001 AVS check failed.
RTMENRE0006 Invalid Account Number
RTMENRE0014 Card Already Expired.
RTMENRE0015 Invalid Card expiration date.
RTMENRE0020 Invalid Security code.
RTMENRE0022 Invalid UserKey.
RTMENRE0026 Enroll User not found
RTMENRE0027 Invalid Community code.
RTMENRE0027 Invalid Community code.
RTMENRE0029 Enrollment record is null.
RTMENRE0030 Bad Card throttle Exceeded.
RTMENRE0032 Max card limit reached.
RTMENRE0035 Invalid Billing Zip.
RTMENRE0036 Invalid Community Code.
RTMENRE0037 Invalid Enrollment Id.
RTMENRE0038 Invalid last four digit of card number.

August 2016 23
Technical Specifications
Enrollment API

RTMENRE0039 Invalid Last Name.


RTMENRE0041 Userkey and Identity Provider combination is invalid
RTMENRE0042 Maximum PAN usage reached.
RTMENRE0043 Authentication Record is null.
RTMENRE0044 Invalid Card number.
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 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

CardNumber string Either CardNumber or CardId

CardId GUID Either CardNumber or CardId

AuthenticationDetails
Fields Data Type M/O
CommunityCode string M
UserProfileId GUID Either UserProfileId or UserKey

24 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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>
<!--Optional:-->
<v7:deleteCardRequest>
<enr:AuthenticationDetails>
<enr:CommunityCode>SANDBOX</enr:CommunityCode>
<!--Either UserKey or UserProfileId should be provided. Both are Mutually Exclusive-->
<!--Optional:-->
<enr:UserKey>test</enr:UserKey>
</enr:AuthenticationDetails>
<!--Optional:-->
<enr:CardNumber>4444555566667777</enr:CardNumber>
</v7:deleteCardRequest>
</v7:DeleteCard>
</soapenv:Body>
</soapenv:Envelope>

2.3.2 DeleteCard Response

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

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>

26 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

Sample DeleteCardResponse: Error


</s:Body>
</s:Envelope>

2.3.3 DeleteCard Errors

Table 2-9: DeleteCard 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
RTMENRE0002 Reached Minimum Number of Cards.
RTMENRE0022 Invalid UserKey.
RTMENRE0026 Enroll User not found
RTMENRE0027 Invalid Community code.
RTMENRE0030 Bad Card throttle Exceeded.
RTMENRE0035 Invalid Billing Zip.
RTMENRE0036 Invalid Community Code.
RTMENRE0037 Invalid Enrollment Id.
RTMENRE0038 Invalid last four digit of card number.
RTMENRE0039 Invalid Last Name.
RTMENRE0043 Authentication Record is null.
RTMENRE0044 Invalid Card number.
RTMENRE0048 Null request.

August 2016 27
Technical Specifications
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.

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

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>
<!--Optional:-->
<v7:request>
<enr:AuthenticationDetails>
<enr:CommunityCode>SANDBOX</enr:CommunityCode>
<!--Either UserKey or UserProfileId should be provided. Both are Mutually Exclusive-->
<enr:UserProfileId>ca5d4409-574e-e111-ba3b-001a4ba980c6</enr:UserProfileId>
</enr:AuthenticationDetails>
</v7:request>
</v7:Unenroll>
</soapenv:Body>
</soapenv:Envelope>

28 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

2.4.2 Unenroll Response

Table 2-11: Unenroll Response Parameters

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

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>

August 2016 29
Technical Specifications
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

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

30 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

7000 Not supported exception


RTMENRE0026 Enroll User not found
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 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

Field Data Element Sample Data Description


Number
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/ VISA M Required entry. Denotes the intended
Destination ID recipient of the file. Must be VISA.
4 File Description ENROLLMENT M Identifies the type of batch request
REQUEST
5 File Create Date 6/1/2015 M The date on which the file was created by the
Sender.
6 File Control 00 O A two-digit sequence value used in case
Number 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.

August 2016 31
Technical Specifications
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 Field Data Type M/O Description


Number
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 M for E, S, D
number 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

32 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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 Data Element Sample Data Description


Number
0 Record Type 99 M Required entry is 00
1 Record SubType 99 M Required entry is 00
2 Record Count - File 15 M Denotes the number of records in the file. If
Level 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

August 2016 33
Technical Specifications
Enrollment API

2 Error Code Any RTM error code listed RTMENRE0000


in the error codes for
Enroll, SaveCard,
DeleteCard and Unenroll
APIs
3 Error Message Message associated with Card already enrolled
code.
4 Community Code SANDBOX
5 UserKey Unique identifier for the 1234567890
enrollee defined by VOP
client
6 UserProfileId Value returned by VOP that 15c922db-57c2-4078-9027-82847bc0f251
uniquely identifies an
enrollee.
7 CardId Value returned by VOP that 20c922db-57c2-4078-5555-82847bc0f251
uniquely identifies a
Personal Account Number
(PAN)
8 CardLast4 Last four digits of a PAN. 5771
9 ReferenceId Unique Id generated by 60c922db-57c2-5566-5555-82847bc0f231
VOP for each API response

34 Visa Confidential August 2016


Visa Offers Platform
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.

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 **

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

BrowserName A descriptive name of the users 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 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.

ContactType Instance of NotificationChannelType. The type of contact, specifically Sms for


text or Email for email,

36 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

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.

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 users cell phone country code

MobilePhoneNumber The enrolled users cell phone number

NameOnCard Name as it appears on the Visa card.

August 2016 37
Technical Specifications
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 users 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.

38 Visa Confidential August 2016


Visa Offers Platform
Enrollment API

August 2016 39