Visa Real Time Messaging - Visa Developer Center · Overview Web Services Implementation Guide - Getting Started 4 Visa Confidential April 2015 2 Overview The Visa Offers Platform

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

Contents

ii Visa Confidential April 2015

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


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



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



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



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



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



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



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



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

https://www.pcisecuritystandards.org/

Security Prerequisites



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


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



Term Definition

Channel Means by which a partner communicates with an enrollee. Examples

include:

Email

Sms (Text message)

Facebook

…

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


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



Term Definition

Examples include:

Text message or “Sms”

Email

Facebook

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


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



Term Definition

Z

Glossary


March 2015 19

Documents

Visa Real Time Messaging - Visa Developer Center · Overview Web Services Implementation Guide - Getting Started 4 Visa Confidential April 2015 2 Overview The Visa Offers Platform