Post on 26-Jun-2018
transcript
Visa Real Time Messaging
Web Services Implementation Guide
Getting Started
Effective Date: April 2015
Visa Confidential
Important Information on Confidentiality and Copyright
© 2015 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
April 2015 Visa Confidential i
Contents
Contents ............................................................................................................................................................................ i
1 About This Guide .................................................................................................................................................. 3
1.1 Purpose............................................................................................................................................................................... 3
1.2 Audience ............................................................................................................................................................................ 3
1.3 Requirements ................................................................................................................................................................... 3
2 Overview ................................................................................................................................................................. 4
2.1 Authorization for Access to Visa Real Time Messaging Data ........................................................................ 4
2.2 Interfaces ........................................................................................................................................................................... 4
2.3 RTM Web Service Usage Test Scenarios ................................................................................................................ 5
2.3.1 Enrollment Life Cycle ............................................................................................................................................. 5
2.3.2 Express Enrollment Life Cycle ............................................................................................................................. 5
2.3.3 Offer Life Cycle ......................................................................................................................................................... 5
2.4 SOAP Message Format ................................................................................................................................................. 6
2.5 Web Service Onboarding ............................................................................................................................................ 8
2.5.1 Certification ............................................................................................................................................................... 9
2.5.2 Visa Real Time Messaging VOL Web Service Account ............................................................................. 9
2.5.3 Visa Digital Signing Certificate ........................................................................................................................... 9
3 Testing ..................................................................................................................................................................... 9
3.1 Internal (Client) Testing .............................................................................................................................................. 10
3.2 Visa Real Time Messaging QA Environment ...................................................................................................... 10
3.3 QA Environment Connectivity Prerequisites ...................................................................................................... 10
3.4 QA Certification Success Criteria ............................................................................................................................ 11
4 Security Prerequisites ........................................................................................................................................ 11
4.1 PCI Data Security Standard ....................................................................................................................................... 11
4.2 PCI Requirements ......................................................................................................................................................... 11
4.3 Penetration Testing ...................................................................................................................................................... 12
Glossary ......................................................................................................................................................................... 13
About This Guide
Web Services Implementation Guide - Getting Started
April 2015 Visa Confidential 3
1 About This Guide
1.1 Purpose
This guide is designed to assist RTM partners in preparing to use the Visa RTM Web Services.
1.2 Audience
This guide is intended for the following individuals:
Application Developers
System Developers
1.3 Requirements
The users of this document must have access to:
RTM Web Services
Visa Online
Overview
Web Services Implementation Guide - Getting Started
4 Visa Confidential April 2015
2 Overview
The Visa Offers Platform provides digital media Program Providers with access to Visa transaction
data, generated in real time. By integrating with Visa Offers Platform, Program Providers can enhance
their own loyalty and offers programs in new and powerful ways.
With appropriate cardholder consent, Visa Offers Platform enables precise targeting of offers based
on individual purchase activity. After offers are delivered, Program Providers can use Visa Offers
Platform transaction data to track qualifying purchases, provide immediate purchase confirmations to
cardholders and determine the appropriate rewards or loyalty points to fulfill.
2.1 Authorization for Access to Visa Real Time Messaging Data
Partners must request the RTM Administration to grant them access to the Web Services. Visa OnLine
(VOL) controls access to Web Services by assigning rights to a VOL partnerID. Hence partners need to
make the following request to RTM Administration to get access to the new RTM Web Services.
Provide Visa with the IP address of the server hosting the RTM client services. Note: This security
requirement precludes hosting RTM clients on mobile devices.
Request a Business ID if they do not already have one.
Request a VOL user ID if they do not already have one.
Request “system” level access for the user ID. Note that the same user ID cannot be used to access
both the Web Services and RTM partner interface.
Request access to the Web Services. The services exposed to each partner are determined by Visa.
Only those services required by the partner’s application will be provided.
2.2 Interfaces
Visa provides a number of interfaces to Real Time Messaging. The partner’s account manager will
work with the partner to determine the interface(s) that are appropriate:
Web Service Quality Assurance Environment (QA) – This is the site for testing connectivity
between the partner’s Web Service client and Visa Real Time Messaging Web Services running
on Visa servers. Web Service client applications will have to successfully complete a connection
to the site and transact a test script with the QA Web Service before they will be allowed to
connect with the production Visa Real Time Messaging Web Service.
Overview
Web Services Implementation Guide - Getting Started
April 2015 Visa Confidential 5
The Visa Real Time Messaging Web Service (Production or PROD) – These services are the only
means of access to information that will be available over the Internet. They provide access to
selected data to which the requester is authorized based on the requester’s Visa Online role.
The Visa Real Time Messaging Enrollee Transaction End Point Messaging Interface- This is the
interface through which a partner receives enrollee transactions.
For partners who will use an RTM Express enrollment web site, Visa provides a query string
interface. The query string interface allows the partner to specify certain data fields on the
primary enrollment page, as variables attached to the inbound https request for the enrollment
page.
2.3 RTM Web Service Usage Test Scenarios
This section describes various testing scenarios that might be used to exercise available services.
2.3.1 Enrollment Life Cycle
1. Cardholder enters profile data in partner’s GUI.
2. Partner uses Enroll web service call to enroll a cardholder.
3. Cardholder makes a transaction.
4. Visa delivers the cardholder’s transaction data to the partner via the end point messaging
interface.
5. Cardholder requests to be unenrolled.
6. Partner uses Unenroll to remove a cardholder.
2.3.2 Express Enrollment Life Cycle
1. Cardholder enters profile data in Visa’s GUI.
2. Partner receives an enrollment message from Visa RTM.
3. Partner sets up an offer in RTM Client Service Center
4. Cardholder makes a transaction that qualifies for the offer.
5. Visa delivers that transaction’s data to the partner.
6. Cardholder requests to be unenrolled in Visa’s GUI.
7. Partner receives unenrollment message.
2.3.3 Offer Life Cycle
The following scenario presents a high level description of the sequence of events that occur during
the life cycle of an offer. Whether an optional branch is implemented or not depends on Visa’s
agreement with a partner.
Overview
Web Services Implementation Guide - Getting Started
6 Visa Confidential April 2015
1. Partner defines an offer in RTM’s Client Service Center (“CSC”). Authorized user defines content
and endpoints for the offer.
2. <Optional>Partner presents an offer opportunity to a community.
3. <Optional>Enrollee signifies an interest in the offer.
4. <Optional>Partner sends a “SaveOfferActivation” message to RTM.
5. <Optional>RTM responds that offer is activated.
6. Partner informs enrollee that offer is activated.
7. Enrollee swipes a card at a merchant site.
8. RTM determines that the swipe satisfies the conditions for the offer. The swipe becomes an
“authorization event” for the offer.
9. RTM sends the partner an end point message for each predefined endpoint.
10. Partner notifies an enrollee of award authorization via a notification channel, i.e. email, Sms…
11. <Optional>RTM detects a settlement event that matches the authorization event.
12. <Optional>RTM communicates the settlement event to the partner.
13. The offer times-out and becomes inactive.
2.4 SOAP Message Format
Figure 3-1 provides a conceptual view of the Visa RTM Web Service request message.
Figure 2-1: Web Service Request Message Contents
Figure 2-1 is a conceptual view of the request message. The outermost wrapper is the SOAP envelope.
(For the purpose of this discussion, HTTP/HTTPS message components are ignored.) Contained within
it are the SOAP header and the SOAP body. The SOAP header contains only the security element. The
security element contains a UserNameToken. The UserNameToken element contains the user name
and password for the Visa Real Time Messaging Web Service access account. The password is included
in clear text since the entire message is encrypted in the SSL channel.
Figure 2-2: Sample SOAP Header
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-
Overview
Web Services Implementation Guide - Getting Started
April 2015 Visa Confidential 7
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-
1.0.xsd">johnsmith</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-
token-profile-1.0#PasswordText">Test123</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
The SOAP body contains the Visa RTM request, the contents of which are specific to the operation
being invoked.
The actual message has additional elements (tags) and is written in XML.
For details of the specific fields, their semantics, and their expected contents, refer to RTM API Guides.
Figure 2-3: Web Service Response Message Contents
Figure 2-3 is a conceptual view of the response message. The outermost wrapper is the SOAP
envelope. (In this figure, we ignore HTTP/HTTPS message components.) The SOAP body is contained
within the SOAP envelope. Since the security element is not included as part of the response message,
the response message does not have a SOAP header.
The SOAP body contains the Visa RTM response, which in turn contains the ServiceResponse and
operation specific data, if any. Assuming the requester is authorized to access the requested data, it is
returned in elements within operation specific response.
The ServiceResponse component consists of two elements:
A Boolean “Success” flag.
If the Success flag is false, the ServiceResponse component contains an array of validation
errors.
For details of the specific fields, their semantics, and their expected contents, refer to RTM API Guides.
Overview
Web Services Implementation Guide - Getting Started
8 Visa Confidential April 2015
2.5 Web Service Onboarding
To gain access to RTM Web Services a prospective partner must negotiate with three Visa
organizations as shown in Figure 2-4.
Figure 2-4: RTM Web Service Onboarding
Table 2-1: Visa Real Time Messaging Web Service Onboarding Process
Action Flow Identifier
Request a “system” level account from your Visa PM. Specify the type of
certificate i.e. Production or QA.
1
Receive Visa Online (VOL) credentials (Username, temporary password) 2
Login to VOL. 3
Receive digital certificate credentials via VOL email. 4
Testing
Web Services Implementation Guide - Getting Started
April 2015 Visa Confidential 9
Action Flow Identifier
Login to Visa Certificate Authority 5
Collect certificate 6
Note: The process for obtaining the required certificate is described in the Visa Real Time Messaging Web Service
implementation section that applies to your partner community.
2.5.1 Certification
Internal testing of the Web Service client can be accomplished using a self-signed certificate. Use of
the Visa Real Time Messaging Test Services (QA or PROD environments) requires a certificate signed
by a Visa-approved Certificate Authority. The process for obtaining the required a Visa-issued
certificate is described in Web Service Onboarding Section.
2.5.2 Visa Real Time Messaging VOL Web Service Account
Testing against the Visa Real Time Messaging Test Service requires a VOL Web Service account for
Visa Real Time Messaging. The account credentials (user name and password) must be included as
part of the request message in the <soapenv:Header> section. Normally, the same account is shared
by all machines in a (load-balanced) cluster. The password is non-expiring; a compromised, lost, or
corrupted password must be remedied manually. The process for obtaining a service account, and the
process for managing account credentials, is described in the Visa Real Time Messaging Web Service
Implementation section that applies to your partner community.
At run time, the Visa Real Time Messaging VOL Web Service Account ID must be set in the
<wsse:Username> (Axis) or <Username> (.NET) element, and the password must be set in the
<wsse:Password> (Axis) or <Password> (.NET) element in the SOAP header. In addition, the Visa Real
Time Messaging VOL Web Service Account ID must be set in the <partnerId> element in the message
request header.
2.5.3 Visa Digital Signing Certificate
The certificate issued by the Visa Certificate Authority expires in one year. Visa will notify the owner of
the VOL account of the pending expiration of a certificate. The Visa Certificate Authority will
automatically renew the certificate upon receipt of a positive response to the email notification. If the
certificate authority does not receive a response to the email, the certificate will be allowed to
expire and service will be cut off.
3 Testing
This chapter provides information about the Visa Real Time Messaging Test Service.
Testing
Web Services Implementation Guide - Getting Started
10 Visa Confidential April 2015
3.1 Internal (Client) Testing
A Visa Real Time Messaging Web Service client that successfully communicates with the development
local server will have to make the following changes to communicate with the Visa RTM QA
environment (QA):
Configure the Web Service client to use a Visa-signed X.509 digital signing certificate.
Configure the Web Service client to use the Visa-supplied Visa Online (VOL) machine account’s
partner name and password.
Ensure that the SOAP Header parameter “mustUnderstand” is nonexistent or null.
3.2 Visa Real Time Messaging QA Environment
To facilitate development of Visa Real Time Messaging Web Service clients, Visa provides the QA Web
Service. QA is a pre-production environment that works with scrubbed (or “not real”) card account
numbers. Prior to connecting to the production environment clients must connect to QA and pass a
series of certification tests. Visa provides the tests, which are designed to exercise regular message
flows as well as a number of edge cases such as exceedingly large response messages, communication
timeouts, and unusual data permutations.
3.3 QA Environment Connectivity Prerequisites
To connect to the Visa Real Time Messaging QA environment, a Web Service client has to have a VOL
partner name and password and digital signing certificate issued by Visa. In addition to security
credentials, the client application must be able to generate digitally signed Web Service requests
compliant with specifications provided by Visa Real Time Messaging Web Service Definition Language
(WSDL). Finally, the client application must be able to establish a Secure Socket Layer (SSL) connection
to Visa servers in QA.
Web Service security implemented in QA is identical to that in the production environment, and
therefore the ability to connect to the QA environment is an important implementation milestone.
Important: Visa requires that connectivity to QA is established from production-ready applications that
have passed internal quality checks.
Security Prerequisites
Web Services Implementation Guide - Getting Started
April 2015 Visa Confidential 11
3.4 QA Certification Success Criteria
Only after a Visa Real Time Messaging Web Service client has demonstrated the ability to conduct
transactions in QA is it allowed to attempt to connect to the production Visa Real Time Messaging
Web Service. To pass this certification requirement, developers must be able to successfully establish
Web Service connectivity and execute all test scripts provided by Visa.
After all tests have been executed, Visa validates that each request has gone through the system. The
client documents the results of each test case as prescribed in the certification test spreadsheet and
provides the complete test report to Visa. QA testing continues until all test cases have documented
results and all results have been reviewed and accepted by both Visa and the client.
All client testing must be executed from an integrated environment, meaning that all systems involved
in servicing the requests should participate in testing.
The term “integrated environment” is a generic term used to describe the client’s environment that
will be used for QA certification. The integrated environment may mean the client’s “production
environment”, “pre-production environment” or “test environment”.
Important: SUCCESSFUL INTERACTION WITH THE TEST SYSTEM IS A CRITICAL IMPLEMENTATION
STEP. WEB SERVICE CLIENTS HAVE TO SUCCESSFULLY COMPLETE A CONNECTION TO QA, INITIATE A
SERIES OF TEST TRANSACTIONS USING BOTH STATIC AND REAL CARD NUMBERS BEFORE THEY ARE
ALLOWED TO CONNECT WITH THE PRODUCTION.
4 Security Prerequisites
There are two security requirements that must be met before a partner will be allowed to interact with
Visa information systems.
4.1 PCI Data Security Standard
All partner organizations must be PCI compliant to use Visa’s Web services APIs. Please refer to
https://www.pcisecuritystandards.org/. There are a number of third party consulting organizations that
perform PCI audits. This requirement is relaxed in cases where the partner is only receiving endpoint
messages.
4.2 PCI Requirements
Control Objectives PCI DSS Requirements
Security Prerequisites
Web Services Implementation Guide - Getting Started
12 Visa Confidential April 2015
Control Objectives PCI DSS Requirements
Build and Maintain a Secure Network
-
- Protect Cardholder Data
-
-
- Maintain a Vulnerability Management Program
-
- Implement Strong Access Control Measures
-
-
-
- Regularly Monitor and Test Networks
Maintain an Information Security Policy
1. Install and maintain a firewall configuration to protect
cardholder data
2. Do not use vendor-supplied defaults for system
passwords and other security parameters
3. Protect stored cardholder data
4. Encrypt transmission of cardholder data across open,
public networks
5. Use and regularly update anti-virus software on all
systems commonly affected by malware
6. Develop and maintain secure systems and
applications
7. Restrict access to cardholder data by business need-
to-know
8. Assign a unique ID to each person with computer
access
9. Restrict physical access to cardholder data
10. Track and monitor all access to network resources and
cardholder data
11. Regularly test security systems and processes
12. Maintain a policy that addresses information security
4.3 Penetration Testing
A penetration test assesses a computer system’s security by simulating attacks from malicious
outsiders. All candidate partners must pass a penetration test prior to being given access to any of
Visa’s information systems.
Glossary
Web Services Implementation Guide - Getting Started
April 2015 13
Glossary
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Term Definition
A
Account Range As a slice of an entire BIN, an account range will define a logical
grouping of card account numbers down to the first 10 digits of a card
account number.
Acquirer
A bank that processes and settles a merchant's daily credit card
transactions, and then in turn settles those transactions with the card
issuer. Merchants must maintain such an account to receive credit for
credit card transactions. Daily card transaction totals are deposited in the
merchant's account after settlement and discount fees are deducted. In
this way, an acquirer serves as the intermediary, to facilitate the credit
transaction and pay the merchant.
Action
An event may have many actions, up to a maximum of one per channel.
Sending an EPM message for an event is an example of an “action.”
B
BID—Business Identification A unique number assigned to any business entity that has a relationship
with Visa. This number is maintained by the Franchise Management
group. Any Real Time Messaging organization may have at least one BID.
Many-to-one relationship to a partner.
C
Campaign Group of related offers for a partner’s community.
Card Product A category of payment instrument that defines procedures, rules, and
options/features, such as credit, debit, charge, or prepaid.
Card Type Distinguishes between the types of cards offered (credit card, debit card,
commercial card, etc.)
Cardholder An individual who possesses a Visa card product.
Cardholder Information Security
Program (CISP)
Mandated since June 2001, the Cardholder Information Security Program
is intended to protect Visa cardholder data—wherever it resides—
ensuring that issuers, merchants, and service providers maintain the
highest information security standards.
Card Last-4 A candidate list of four-digit numbers from which a user must identify
one that matches the last four digits of one of his or her enrolled cards.
Glossary
Web Services Implementation Guide - Getting Started
14 Visa Confidential April 2015
Term Definition
Channel Means by which a partner communicates with an enrollee. Examples
include:
Sms (Text message)
…
Clearing During the clearing process the acquirer provides the appropriate issuer
with information on the sale. No money is exchange during clearing.
Clearing involves the exchange of data only. The acquirer provides data
required to identify the cardholder’s account and provide the dollar
amount of the sales. When the issuing bank gets this data, the bank
posts the amount of the sale as a draw against the cardholder’s available
credit and prepares to send payment to the acquirer.
Community Collection of partner enrollees. Many-to-one relationship to a partner.
Contact Type An attribute associated to each Visa Real Time Messaging person
contact, and each person contact can be associated to one or more
attributes. Contact types include email, text, telephone, …
Contacts Organizations or Persons that are maintained within Visa Real Time
Messaging
CSA Customer Service Associate
CSC Client Service Center
D
E
End Point Message An https message delivered to a partner by RTM.
Event Many-to-one relationship to an offer. A real-time action by an enrollee
that meets some predefined criteria. Examples include:
Enrollee activates an offer presented to the enrollee by a partner.
Enrollee makes a card swipe satisfying the conditions of the
offer.
F
Fulfillment The awarding of the benefits of an offer.
G
GCAS Global Customer Assistance Service—A suite of services offered to all
Glossary
Web Services Implementation Guide - Getting Started
April 2015 15
Term Definition
Visa issuers worldwide by the VCCS & its service partners.
GUID Global User ID
GMT - Greenwich Mean Time The date and time standard used by Visa systems.
H
I
Identity Provider Identifies the organization that maintains a community’s credentials
store.
Issuer Any association member financial institution, bank, credit union or
company that issues, or causes to be issued, Visa cards to cardholders
J
JSON JavaScript Object Notation. A formatting option for an end point
message.
K
L
Last Four List A candidate list of four-digit numbers from which a user must identify
one that matches the last four digits of one of his or her enrolled cards.
M
MCC A Merchant Category Code is a four-digit number assigned to a business
by MasterCard or VISA when the business first starts accepting one of
these cards as a form of payment. The MCC is used to classify the
business by the type of goods or services it provides. In the US it can be
used to determine if a payment needs to be reported to the IRS for tax
purposes.
MSA In the United States a Metropolitan Statistical Area (MSA) is a
geographical region with a relatively high population density at its core
and close economic ties throughout the area.
N
Notification Many-to-one relationship to an offer. Enrollee is informed of having
satisfied the conditions of an offer and is presented with the means of
obtaining its benefits.
Notification Channel "The means by which an enrollee is informed of having satisfied an offer.
Glossary
Web Services Implementation Guide - Getting Started
16 Visa Confidential April 2015
Term Definition
Examples include:
Text message or “Sms”
O
Offer Many-to-one relationship to a Campaign. An opportunity to receive
benefit for a targeted enrollee. Fulfillment contingent on a set of
conditions. Transactions meeting the conditions trigger events.
P
PAI Personal Account Information. According to Visa’s key controls any
person or organization that has access to personal information must
observe specific security practices to maintain the privacy and security of
the entrusted information. In the case of a partner Visa requires the
organization to be certified as PCI compliant.
Pen Test Penetration Testing. Extensive test to identify potential vulnerabilities to
hacking in partner software systems.
PCI Security Standards The Payment Card Industry Data Security Standard (PCI DSS) is an
information security standard for organizations that handle cardholder
information for the major debit, credit, prepaid, e-purse, ATM, and POS
cards.
Q
R
REST Representational State Transfer is a style of software architecture for
implementing Web based applications.
RTM Real Time Messaging
RPIN The rewards program identification number of an issuer’s portfolio as
maintained in the Rewards Program Manager (RPM) Application.
S
Segment A database query run nightly to select a target group of enrollees.
Settlement The second step is the actual exchange of funds. The issuer sends a
record of money that is being transferred from its account to that of the
acquirer. From this account the acquirer pays the merchant. Funds are
settled between issuers and acquirers through accounts with large banks
that are members of the Federal Reserve System and have been selected
Glossary
Web Services Implementation Guide - Getting Started
April 2015 17
Term Definition
for that purpose. Payments to merchants are made usually through the
Federal Reserve’s Automated Clearing House (the “ACH”) which is an
electronic funds transfer system.
SOAP SOAP is a protocol specification for exchanging structured information in
the implementation of a Web Service.
SSL Secure Socket Layer
T
Tag A database query to identify (“tag”) a target group of enrollees. Tag
queries are run on demand. Can be promoted to a “segment.”
Tag Group A higher level grouping of related tags. Examples include Affinities,
Contact Preference, and Enrollment mode.
U
V
VCCS Visa Call Center Services or Visa Customer Care Services
VIS – Visa Information System Visa’s corporate repository for Partner and non-Partner legal and
contractual information, including:
Visa An organization type in Visa Real Time Messaging that is used to define
the organization as part of the Visa Company, which would apply to ALL
issuers in Visa Real Time Messaging.
Visa Real Time Messaging The centralized system that manages real-time marketing information.
Visa Incentive Network (VIN) A robust platform designed to assist issuers in distributing rewards to
cardholders in the form of merchant and category-wide offers; a core
eligibility requirement for issuers of both Visa Signature and Visa
Traditional Rewards.
Visa Online (VOL) Visa’s system for controlling partner access to Visa’s online systems.
W
X
XML Extensible Markup Language is a markup language that defines a set of
rules for encoding documents in a format
Y
Glossary
Web Services Implementation Guide - Getting Started
18 Visa Confidential April 2015
Term Definition
Z