visa offers platform - visa developer center€¢ technical specification and requirements for...
Post on 17-Apr-2018
262 Views
Preview:
TRANSCRIPT
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
Visa Offers Platform Enrollment API
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
Visa Offers Platform Enrollment API
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
4 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
August 2016 5
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
Technical Specifications
Enrollment API
6 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
August 2016 7
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>
Technical Specifications
Enrollment API
8 Visa Confidential August 2016
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>
Visa Offers Platform Enrollment API
August 2016 9
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>
Technical Specifications
Enrollment API
10 Visa Confidential August 2016
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>
Visa Offers Platform Enrollment API
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>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>
Technical Specifications
Enrollment API
12 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
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
Technical Specifications
Enrollment API
14 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
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>
Technical Specifications
Enrollment API
16 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
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.
Technical Specifications
Enrollment API
18 Visa Confidential August 2016
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.
Visa Offers Platform Enrollment API
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.
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
Technical Specifications
Enrollment API
20 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
August 2016 21
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
Technical Specifications
Enrollment API
22 Visa Confidential August 2016
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>
Visa Offers Platform Enrollment API
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
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.
Technical Specifications
Enrollment API
24 Visa Confidential August 2016
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 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.
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
Visa Offers Platform Enrollment API
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> <!--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
Technical Specifications
Enrollment API
26 Visa Confidential August 2016
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>
Visa Offers Platform Enrollment API
August 2016 27
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.
Technical Specifications
Enrollment API
28 Visa Confidential August 2016
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>
Visa Offers Platform Enrollment API
August 2016 29
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>
Technical Specifications
Enrollment API
30 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
August 2016 31
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 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.
Technical Specifications
Enrollment API
32 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
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
Technical Specifications
Enrollment API
34 Visa Confidential August 2016
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
Visa Offers Platform Enrollment API
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 **
Technical Specifications
Enrollment API
36 Visa Confidential August 2016
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,
Visa Offers Platform Enrollment API
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.
Technical Specifications
Enrollment API
38 Visa Confidential August 2016
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.
Visa Offers Platform Enrollment API
August 2016 39
top related