rupay- paysecure issuer integration guide version 1.6 14 ... · rupay issuer integration guide...

RuPay Issuer Integration Guide

Version 1.6 – 14 May 2018 Confidential of 52

RuPay- PaySecure Issuer Integration Guide

Version 1.6 – 14 May 2018


Version 1.5 – 03 April 2018 Confidential of 52

Contents

A. Objective of the document .......................................................... 11

B. RuPay eCommerce solution branding / RuPay Mark / PaySecure Mark .... 11

C. References and publications ........................................................ 11

1. Introduction ............................................................................................................................. 12 1.1 NPCI eCommerce Solution: PaySecure ....................................................................................................... 12 1.2 Participants in the RuPay eCommerce transaction cycle ........................................................................... 13 1.3 Defining roles of Entities ............................................................................................................................. 14 1.4 Architecture for authentication of RuPay online transactions ................................................................... 16

2. Transaction Flow ....................................................................................................................... 17 2.1 Iframe Flow ................................................................................................................................................. 17 2.2 Redirect Flow .............................................................................................................................................. 19

3. I-frame - Transaction Processing ................................................................................................ 22 3.1 Auth_Initiate ............................................................................................................................................... 22 3.2 Cardholder Control Pass to Issuer............................................................................................................... 22 3.3 Issuer Authentication of Cardholder using OTP .......................................................................................... 23 3.4 Cardholder Control return to PaySecure .................................................................................................... 24 3.5 Auth_Result ................................................................................................................................................ 24

4. Redirect - Transaction Processing .............................................................................................. 25 4.1 Auth_Initiate ............................................................................................................................................... 25 4.2 Cardholder Control by Issuer ..................................................................................................................... 25 4.3 Issuer Authentication of Cardholder .......................................................................................................... 26 4.4 Cardholder Return Browser Control ........................................................................................................... 28 4.5 Auth_Result ................................................................................................................................................ 31

5. Transaction ID ........................................................................................................................... 31

6. Time out scenarios and handling ............................................................................................... 31 6.1 PaySecure-to-Issuer (during Auth Initiate API) ........................................................................................... 31 6.2 Cardholder-to-Issuer (during cardholder interaction) ................................................................................ 31 6.3 PaySecure-to-Issuer (during Auth_Results API) .......................................................................................... 32 6.4 Time Out Details ......................................................................................................................................... 33

7. System Security Features .......................................................................................................... 33 7.1 Issuer Authentication methods .................................................................................................................. 33 7.2 Transport Security....................................................................................................................................... 34 7.3 Cardholder/ Shopper Browser Authentication Methods............................................................................ 34 7.4 Separation of Card details/PAN and OTP authentication mechanism ........................................................ 34 7.5 Web Application Firewall ............................................................................................................................ 34

8. Integration Requirements ......................................................................................................... 34 8.1 Connectivity to NPCI’s PaySecure product ................................................................................................. 35 8.2 Connectivity to NPCI’s PaySecure product ................................................................................................. 35

9. Web-Services API Call & Example .............................................................................................. 35 9.1 Auth_Initiate API Call .................................................................................................................................. 36 9.2 Auth_Results API Call .................................................................................................................................. 37

10. Issuer Authentication Server.................................................................................................. 38

11. Member bank pre-requisites & Issuer On-Boarding ................................................................ 38 11.1 Member bank pre-requisites ...................................................................................................................... 38 11.2 Issuer On-Boarding ..................................................................................................................................... 39

12. Best Practices ........................................................................................................................ 39 12.1 Transaction Review and Filtering ................................................................................................................ 39 12.2 Network and Infra Security ......................................................................................................................... 39



12.3 Adhere to the PCI Data Security Standard Requirements .......................................................................... 40 12.4 Suspicious transactions to be monitored: .................................................................................................. 40 12.5 Cardholder acquisition ................................................................................................................................ 40 12.6 Drafts SMS’s Suggested for Issuer .............................................................................................................. 41

Annexures A - Message Format ................................................................. 43

Annexures B - Error Code/messages ........................................................... 49



Document History

Document Title RuPay Issuer Integration

Document

Business/Functional

Requirements Document

Document Owner RuPay eCommerce Team

Version Release Date Prepared/Review by Comments

1.0 14/08/12 NPCI eCommerce team Initial Draft Version

1.1 14/02/13 NPCI eCommerce team Revised Version

1.2 01/08/13 NPCI eCommerce team Revised Version

1.3 24/03/15 NPCI eCommerce team Version V1.3




Document Change Control

Date of

Change

Version

Number

Section/Reference

Number

Reason

for

Change

Summary of

Change

CCR

Nu

mbe

r

01-08-13 V1.2

Added section 2.4 High

value transaction flow ,

Page: 22

01-08-13 V1.2 Removed Invalid PIN logic

15, Page: 34

01-08-13 V1.2

Added section 11. High

value transaction, Page:

36

01-08-13 V1.2

Added 17.1 time out details

Page: 38

01-08-13 V1.2

Added section 26.4.2

Custom Pin Pad design,

Page:55

01-08-13 V1.2

Added HV - high value for

Customer status in

auth_initiate call, Page: 61

01-08-13 V1.2

Added issuer error codes

in error codes section,

Page: 70

19-10-13 V1.3 Added section 1.2 This part



Transaction Flow –

Cardholder Point of view

Page : 11

was not included in earlier versions. The addition is based upon observations during meetings with banks

19-10-13 V1.3

Added new figure for

section 1.4 Architecture

for authentication of

RuPay online transactions.

Page : 12

The diagram in version 1.2 did not depict the linkages clearly, the new diagram depicts the role of each interface clearly

20-10-13 V1.3

Removed section 1.7 High

Level steps for the issuer

Page: 13

covered in section 2.4 High value transaction flow

20-10-2013 V1.3 2.1 Inflight Transaction Initiated Enrollment Page 15

For better understanding of transaction flow

Reordered

some steps

20-10-13 V1.3

Changed steps & figure for

section 2.4 High Value

Transaction Flow

Page: 21

Enhanced steps and diagram

20-10-13 V1.3

Edited section 3.1 Decline

ISO scenarios

Page: 24

Included more information on



steps for clarification. Added two scenarios which were not depicted earlier.

20-10-2013 V1.3 5 Issuer Initiated Enrollment Page 71

The diagram in previous verison did not depict the linkages clearly, the new diagram depicts the role of each interface clearly

New Diagram

20-10-13 V1.3

Removed section 6:

Transaction Type,

7:Transaction Status & 8:

Refund Processing

Page: 33

Not related to Issuing bank

20-10-2013 V1.3 Section 9 to Section 16 Page 34-35

For better understanding of transaction different stages

Reordered

20-10-13 V1.3

Removed section 18.1 :

Merchant Authentication

methods, 18.2 : Acquirer

Authentication Methods

Page : 38


20-10-2013 V1.3 18.8 : SSL Connection

New diagram depicts the

New Diagram

Added



connection between involved parties.

20-10-2013 25.3 Adhere to the PCI Data Security Standard Requirements


Removed

Section

20-10-13 V1.3

Removed section 26.4

Member bank pre-

requisites

Page: 52

Had been already covered at another place in same document (Section 23, page 48)

21-10-13 V1.3

Removed section 26.5.2 :

RuPay Online

Authorization

Certification

Page : 56

This is about RGCS certification, not relevant for PaySecure

21-10-13 V1.3

Removed section 26.5.3 :

Day zero verification

Page : 56


21-10-13 V1.3

Removed section 26.5.3:

Comfort & User

Acceptance Testing

Page : 56


21-10-13 V1.3 Removed section 26.5.4: This is



Review of Message logs

Page : 56

about RGCS certification, not relevant for PaySecure

21-10-13 V1.3

Section : Annexures C - Error Code/messages: Added Error code 56 & 411 for issuer Page : 79 Page : 81

Since these codes were not defined, Issuing bank would send any error for said scenarios. This will also hamper the MIS. To avoid this specific error codes are define.

Added Error Codes: Error code 56: Card number not present in IAS system. Error code 411: Mobile number is not present for the card at IAS

21-10-2013 V1.3 Annexure A: FAQ

Only few pointers were included in earlier version. This addition is based upon observations during meetings with banks

Enhanced Section to add more FAQ's

22-10-13 V1.3 Added Few Points to Section: 1.1. NPCI eCommerce Solution:

To provide more



PaySecure Page 11

details and clarity to product features

25-03-2015 V 1.3 Updated 1.2.2

Page : 16 ( New)

Removed the

anti-phishing

page details

25-03-2015 V 1.3 Updated 1.4.3 (Previously 1.3.3)

Page: 10

Removed the

anti-phishing

page details

25-03-2015 V 1.3

Updated 2.2: Post Enrolment Transaction Processing.

Page : 18

Removed the

anti-phishing

page details

25-03-2015 V 1.3 Updated 14 : Phrase

Page : 36

Removed the

anti-phishing

page details

25-03-2015 V 1.3 Removed 15 : Last 3 Transactions

Page: 36

Removed the

anti-phishing

page details

25-03-2015 V 1.3 Updated Annexure A

Page: 58

Removed the

anti-phishing

page details

25-03-15 V1.3

Section : Annexures C - Error Code/messages: Added Error code 413, 414, 415 & 416 for issuer Page : 67

Since these codes were not defined, Issuing bank would send any error for said scenarios. This will also hamper the MIS. To avoid this specific error codes are

Added Error Codes: Error code 413: Invalid CVD entered by Cardholder. Error code 414: Expired Card.

Error Code 415:

Card is reported as Lost.

Error Code 416:

Card is reported as Stolen.



define.

01-08-2016 V1.4 Included new authentication methods

Included new authentication methods

01-04-2018 V1.5 Updated Multiple section and pages of the document

Yearly review

Re-direction flow

I-frame Flow

error codes and their descriptions

11-05-2018 V1.6 Introduced hashing mechanism for MIMA



A. Objective of the document

The RuPay Issuer Integration Guide is intended for Issuer banks and their service providers

that are evaluating or have decided to implement the RuPay eCommerce solution. This guide

explains the RuPay eCommerce solution and its benefits, transaction flows, and

implementation planning and considerations. The objective is to help the Issuing bank plan

the development, testing, certification, and production setup of the RuPay eCommerce

solution.

This guide is targeted at the Project Manager, Functional and Technical integration resources

tasked with implementing PaySecure solution for their gateway. The focus is online checkout

interaction.

B. RuPay eCommerce solution branding / RuPay Mark / PaySecure Mark

Refer RuPay Card Marks and Specifications for this section.

C. References and publications

This document must be read in conjunction with the following documents:

► RuPay Card Marks and Specifications

► RuPay IIN Maintenance Manual

► RuPay Bylaws

► RuPay Implementation Guidebook

► RuPay Online Member Manual

► RuPay Dispute Management Rules and Regulations

► RuPay Global Clearing and Settlement Manual

► RuPay Product Manual

► RuPay eCommerce White Paper

► RuPay Acquirer Integration Guide

► RuPay Fraud Risk Management

► Member Certification Guidebook



1. Introduction

1.1 NPCI eCommerce Solution: PaySecure

RuPay, the card scheme launched by the National Payments Corporation of India (NPCI),

has been conceived to fulfil RBI’s vision to offer a domestic, open-loop, multilateral system

which will allow all Indian banks and financial institutions in India to participate in the

electronic payments market. RuPay’s strategic objectives include assisting in digitization of

cash payments, creating a common platform for all banks & payment forms/channels,

becoming a ‘top of the wallet card’ for all Indian consumers across segments, providing a

viable domestic option to Indian banks and acting as a nodal body for the electronics

payment industry.

RuPay, being the first domestic card scheme, is in a unique position to work together with

banks and other entities including government, public sector and private sector entities to

increase the cards spends as a percentage of personal consumption expenditure. The

RuPay card aims to deliver to the stakeholders a convenient and easy e-commerce

experience without compromising on the security and risk. The online PaySecure module

hosted by NPCI for RuPay cards would:

Reduce customers’ effort

Require minimal changes to stake holders system

Quick on-boarding process for merchants

No compromise on security and risk

The solution offers enhanced security measures and is compliant to the RBI

mandated 2-Factor authentication

User friendly and smooth adaptability

Simplified architecture & transaction flow reduces transaction time, resulting in

faster transaction processing and reduction in drop-outs

Customer Experience: During the online payment the cardholder’s authentication

data is collected in a secured manner

The solution will involve use of dynamic One-time-Password as an additional factor of

authentication for e-commerce transactions on internet using RuPay Debit cards and

Credit Cards.

RuPay has adopted the PaySecure solution for enabling a second factor authentication in

the web based channels. The objective is to improve both Cardholder and Merchant

confidence in Internet purchases and to reduce disputes and fraudulent activity related to

the use of Debit cards and Credit Cards online.

PaySecure can be used at various internet accessible devices like Personal or shared

computers. PaySecure is functional for RuPay cardholders of any issuing bank and at any

merchant website which are integrated to RuPay eCommerce solution.



1.2 Participants in the RuPay eCommerce transaction cycle

The RuPay e-Commerce architecture involves the following constituents:

1.2.1 Cardholder: Card holder means any customer in possession of a payment card (RuPay Debit

cards or Credit Cards)

1.2.2 Merchant: The merchant website which has online shopping feature enabled i.e. the website

permit customers to purchase goods/products/services online and pay for the

purchased goods/services/utilities in an electronic manner (Payment cards, net

banking etc.).

1.2.3 Acquirer Bank Payment Gateway: A payment gateway facilitates the transfer of information between a payment portal

(such as a website, mobile phone or IVR service) and the Front End Processor or

acquiring bank. Payment gateways protect card details by encrypting sensitive

information, such as card numbers etc., to ensure that information is passed

securely between the customer and the merchant and also between merchant and

the payment gateway.

Cardholder

Issuer Authentication

Server

Issuer Switch

PaySecure System

NPCI Switch

Acquirer Gateway

Merchant

Issuer NPCI Acquirer



1.2.4 Issuer Authentication Server: The IAS(Issuer Authentication Server) will be responsible to confirm the card

holder authenticity. For the e-Commerce solution, the customer is re-directed to

Issuer bank’s IAS(Issuer Authentication Server) module maintained and managed

completely by Issuing bank for the authentication purpose. Issuing bank will use

any authentication method defined as per bank policy. NPCI recommends to use

dynamic OTP to authenticate the cardholder. The issuer bank would be responsible

for properly authenticating the identity of the cardholder and confirming the correct

status of authentication back to NPCI.

Note: “It is advisable that Mobile number details should be maintained on IAS and

updated daily so that Issuer switch won’t be queried each time for every transaction to

get the mobile number details.”

1.2.5 Issuer Switch: Customer’s card information along with an indicator of authentication successful

will be shared with the Issuing bank to be routed to the bank’s switch wherein the

bank uses this information to authorize/decline the transaction according to pre-

defined rules.

1.2.6 NPCI PaySecure System: This forms the core of the whole NPCI e-Commerce solution. This module is

responsible for various activities such as receiving card information from payment

gateway, providing the mechanism for re-directing customer to issuer page for

authentication etc.

1.2.7 NPCI Switch: The switch is maintained and operated by NPCI for all electronic transactions ATM,

POS etc. For e-Commerce purposes, switch would be required for routing

information from NPCI to Issuing Banks.

1.3 Defining roles of Entities

1.3.1 Role of Merchant Perform integration with the acquirer using acquirer’s API.

To present the cardholder with the shopping and payment page, to include the

integration of the PaySecure consumer screens into the merchant website.

Send the purchase and card related information to the acquirer.

Receive authorization response information from Acquirer

Present the receipt page to the customer and deliver the goods / service upon

confirmation of payment from acquirer.

1.3.2 Role of Acquirer



Acquirer need to integrate their system to PaySecure System using NPCI’s API.

SOAP (Simple Object Access Protocol) web services will be used for messaging

between Acquirer and PaySecure system.

Acquirer to integrate merchant to acquirer’s system using acquirer’s API.

To perform merchant authentication before sending the data to NPCI.

Guide merchants on the best practices that need to be adopted.

Settlement and reporting with the merchants.

1.3.3 Role of Issuer Issuer verifies the card/cardholder as per the current authentication and

authorization process.

Parse the ISO Message block received in the ISO 8583 message from NPCI to

check the authentication indicator.

Issuer to authorize or decline the transaction.

Park the funds related to the authorized transactions and service fees/charges,

if any, in the settlement account.

Liability of all e-Commerce fraud transactions lies with the issuer.

Issuer authenticates the cardholder.

It is recommended to decline/drop the financial transaction if customer clicks

back button or reload (F5) on OTP (IAS Page).

1.3.4 Role of the Cardholder To identify and select the goods or service on the merchant website

To fill in the purchase form (customer name, phone number, email id, delivery

address etc.)

To select the payment option

Upon prompt, enter the card number, expiry date and cvd2 on the payment

page.

Card holder to Authenticate with Issuer by entering OTP on his/her registered

mobile number

1.3.5 Role of NPCI NPCI will certify acquiring and issuing banks system for exchanging data

between the bank and NPCI over web services calls.

NPCI will provide secure communication mechanism between acquirers and

issuers for processing the eCommerce transaction.

Will form ISO 8583 message packet along with successful OTP authentication

indicator.

To route authorization request message with Tag elements (for Card+OTP) to

the issuer.

Guide acquiring banks on merchant certification process, merchant

authentication best practices.

Guide acquiring banks on the best practices that the merchant can follow.

To perform Geo location on the Cardholder’s IP address.



Conducts Clearing & Settlement amongst various stakeholder

Coordinates for disputes for transactions processed using NPCI system.

1.4 Architecture for authentication of RuPay online transactions

1.4.1 High-Level Steps involved in PaySecure Process

1. The Merchant will present cardholder the same shopping and payment web-

pages which are currently in production and active.

2. On the payment page

a) Merchant requests the Acquirer to check the first nine digits of the card

number, called a BIN, to determine if the card is enrolled for eCommerce

transactions by Issuing bank.

b) Acquirer submits a SOAP web-service call to initiate a transaction.

c) For authentication of cardholder by Issuing system, following are the steps

basis the different authentication method:

(i) Redirect Flow - Acquirer will redirect cardholder to Issuer OTP page for

authentication and on submission of correct OTP by cardholder, Issuer

will re-direct back to acquirer with successful response.

(ii) iFrame Flow - Acquirer displays a modal iFrame which is hosted by the

NPCI PaySecure system and PaySecure gives control to Issuing bank

which loads the OTP page, sends the OTP and authenticates the

customer. The authentication result is shared with NPCI.

Acquirer is supplied a response form modal dialog as it closes indicating

that OTP was authenticated successfully and transaction is ready for

authorization.

d) Acquirer completes its business rules and submits an authorization call to

NPCI for transaction authorization.



e) Authorization request is forwarded to PaySecure via a SOAP based web

service call that creates the ISO message, adds the successful OTP

authentication tag and sends to the issuer for authorization. Response is

routed back to merchant through the acquirer.

3. Merchant present the receipt page to the customer

2. Transaction Flow

2.1 Iframe Flow

Step 1 Cardholder accesses/log on to the merchant website, selects the

goods/services that he/she intends to purchase, he/she adds the

goods/services to the shopping cart.

Cardholder now moves to the checkout process.

On the checkout page (payment page) merchant website allows the

cardholder to enter his card information on the merchant website.

Cardholder selects the card type from the options provided by the merchant

on the website. (card type example: RuPay)

Now option to enter following will be provided by the merchant (acquirer /



aggregator), it depends on acquirer integration process.

Card Type

Card number

Expiry date

Card Verification Data 2 (CVD2)

Current functionality supports -13-19 card number length.

Cardholder now clicks on the submit button.

Merchant.Js is downloaded from PaySecure application on cardholder browser

during this process.

Step 2 Merchant sends the complete payment data to Acquirer.

Step 3 Acquirer sends First 9 digits of card-number to PaySecure in Check Bin API

call to determine if the card is eligible for eCommerce transaction. Upon a

successful BIN check, the Acquirer sends in a request to Initiate the

transaction to PaySecure.

Step 4 Acquirer system sends Initiate API call, which contains the payment data, to

PaySecure system

Step 5 Based on BIN PaySecure identifies transaction flow.

Step 6 PaySecure sends, Auth_Initiate API call, the request for authentication to the

issuer authentication server for the verification of card number & mobile

number availablity.

Step 7 PaySecure receives the response from issuer authentication server.

Step 8 PaySecure responds to Initiate API call with transaction details allowing the

Acquirer to continue with the payment process.

Step 9 Acquirer substantiates the PaySecure iFrame overtop of their payment page

for Consumer interaction with PaySecure. PaySecure now has direct

communications and control of the cardholder browser.

Step 10 PaySecure system redirects to issuer OTP Page. The Issuer now has direct

communications and control of the consumer browser.

Step 11 The Issuer provides cardholder with available authentication options.

For example:

Enter OTP

Step 12 Cardholder enters OTP on issuer OTP page.

Step 13 Issuer validates OTP as entered by cardholder on OTP page.



Step 14 Issuer passes the control of iFrame and cardholder back to the PaySecure

system. PaySecure server query’s IAS server via Auth_Result API call to

securely confirm the result and method of cardholder authentication.

Step 15 iFrame is closed, Acquirer is notified by PaySecure through browser only if

OTP authentication status is successful.

Step 16 Acquirer completes any pre-authorization steps and send Authorization

_API request to PaySecure.

Step 17 PaySecure will create the ISO message, as per Rupay specifications with

Mandatory Tag elements and will send the authorization message to the NPCI

switch.

Step 18 NPCI switch sends the authorization message to the issuer switch for

authorization.

Step 19 Issuer switch will validate the ISO Message and will approve/decline the

transaction. Issuer will send the response back to the NPCI Switch.

Step 20 NPCI Switch will send the response to the PaySecure system.

Step 21 PaySecure system sends the response back to the acquirer.

Step 22 Acquirer sends the response to the merchant website.

Step 23 Merchant displays appropriate message to cardholder.

2.2 Redirect Flow

Step 1 Cardholder comes onto the merchant website, selects the goods/services that



he/she intends to purchase, he/she adds the goods to the shopping cart.

Cardholder now moves to the checkout process.

On the checkout page (payment page) merchant website allows the

cardholder to enter his/her card information on the merchant website.

Cardholder selects the card type from the options provided by the merchant

on the website. (card type example: RuPay)

Now option to enter following will be provided by the merchant (acquirer /

aggregator), it depends on acquirer integration process.

Card Type

Card number

Expiry date

Card Verification Data 2 (CVD2)

Current functionality supports -13-19 card number length.

Cardholder now clicks on the submit button.

Step 2 Merchant sends the complete payment data to Acquirer.

Step 3 Acquirer sends First 9 digits of card-number to PaySecure in Check Bin2 API

call to determine if the card is eligible for eCommerce transaction.

Step 4 Based on BIN, PaySecure identifies transaction flow. If BIN not enabled for

redirection flow then same will be mentioned in CheckBin2 Response, then

Acquirer needs to follow Iframe Flow. Upon Successful Bin Check PaySecure

Responds to Acquirer.

Step 5 Acquirer system sends Initiate2_API call to transmit the payment data to

PaySecure system.

Step 6 PaySecure sends Auth_Initiate API call to transmit the request for

authentication to the issuer authentication server (IAS).

Step 7 PaySecure receives the response from issuer authentication server.

Step 8 PaySecure responds to Initiate2_API with transaction details along with

Issuer OTP Page URL and Cardholder ID allowing the Acquirer to continue

with the payment process.

Step 9 Acquirer redirects to the Issuer OTP Page URL received in Initiate2 API

response for cardholder interaction with IAS. IAS System now has direct

communication and control of the cardholder browser.

Step 10 The Issuer provides cardholder with available authentication options to the



cardholder.

For example:

Enter OTP

Step 12 Cardholder enters OTP on issuer OTP page.

Step 13 Issuer validates OTP as entered by cardholder on OTP page.

Step 14 **Issuer redirects cardholder browser back to Acquire system along with

authentication status of cardholder.

Step 15 Acquirer completes any pre-authorization steps and sends

Authorization_API request to PaySecure.

Step 16 PaySecure server queries IAS via Auth_Result API call to securely confirm

the result of cardholder authentication.

Step 17 On Successful receipt of Auth_Result API response from IAS, PaySecure will

create the ISO message with Mandatory Tag elements and will send the

authorization message to the NPCI switch.

Step 18 NPCI switch sends the authorization message to the issuer switch for

authorization.

Step 19 Issuer switch will validate the ISO Message and will approve/decline the

transaction. Issuer will send the response back to the NPCI Switch.

Step 20 NPCI Switch will send the response to the PaySecure system.

Step 21 PaySecure system sends the response back to the acquirer.

Step 22 Acquirer sends the response to the merchant website.

Step 23 Merchant displays appropriate message to cardholder.



3. I-frame - Transaction Processing

On issuer side, transaction involves two server to server API calls namely Auth_Initiate and

Auth_Results and browser interaction for capturing and validating OTP. Details of steps are

provided below

3.1 Auth_Initiate The Auth_Initiate API call is used for checking card details as provided by Cardholder.

PaySecure will securely pass the card details including card number, expiry date and CVD2 to

the issuer in this call. Issuer needs to validate the card status and mobile number status and

this information can be used by issuer to determine the available authentication method to

authenticate the cardholder. In response of Auth_initiate API request the Issuer will supply

Issuer Guid, URL ID, Unique value and Cardholder ID of the authentication page, Issuer GUID,

Unique Value and card holder ID are unique values generated by issuer for each transaction

and are supplied to NPCI as part of Auth_Initiate response.

3.2 Cardholder Control Pass to Issuer PaySecure will pass security parameters to acquirer (PG) as part of API response. The

Acquirer loads iFrame, and pass control of the cardholder to PaySecure. In order to validate

session, the security parameters, as received by acquirer PG as part of API response, are

passed back through browser to PaySecure and same are validated by PaySecure.. The

PaySecure system will call Issuer OTP page URL (against the URLID received as part of

Auth_Initiate response) inside issuer Iframe and passes Cardholder ID (received as part of the

Auth_Initiate API response from IAS) in query string format. IAS has to validate card holder ID

to continue the session. Post validating the session OTP Page is rendered by IAS within the



issuer Iframe. At this stage IAS should pass ‘ISSUER999’- (Modal Popup was opened

successfully, no action required) to cardholder browser by calling relevant JS function

Note: ** Along with cardholderid passed in query string format for OTP Page URL to issuer, an additional parameter name “UID” will also be passed with value “m” for all mobile based transactions. This is to indicate the issuing bank that transaction has been initiated from mobile device and basis such notification, Issuer can display the responsive OTP page designed for mobile devices screens.

3.3 Issuer Authentication of Cardholder using OTP The Issuer now has total control of the cardholder browser through issuer iFrame. The issuer

will utilize this session to interact with the cardholder and authenticate based on

authentication method.

The issuer iFrame window size available for bank usage is 500x320 pixels. Find below sample

illustration of the iFrame.

In order to provide a consistent ecommerce shopping experience, the bank’s screen layout

should have their logo placed in the top left corner, and should provide a cancel button. It is

recommended that the issuer has to complete the OTP authentication process within a

single page within the issuer iFrame screen. This will ensure that overall transaction

processing time/transaction hops is/are not increased. Issuer Bank/IAS should send OTP

to registered mobile number (RMN) of Cardholder. Cardholder enters the OTP received on

Issuer OTP page and submits the same. IAS should validate the OTP and should provide



relevant communications to Cardholder browser, by calling relevant JS function, as

provided in Table below:

–

1 ISSUER000 Authentication was completed successfully, move to

Authorization

2 ISSUER100 Cardholder failed Authentication

3 ISSUER200 Cardholder pressed ‘cancel’ button

4 ISSUER400 Cardholder was inactive and was timed out of the

session

5 ISSUER600 Invalid data was posted to Issuer

6 ISSUER800 General catch all error

3.4 Cardholder Control return to PaySecure The Issuer will return control of the cardholder to PaySecure simply by calling a JavaScript

function provided by PaySecure.

Shown below is a detailed example. For details please refer JavaScript document.

<script language="javascript" src="<Issuer Scripts url>" type="text/javascript">

// This script has to be written in the header part of the html code. It will be

pulled from Paysecure

</script>

<script language="javascript" type="text/javascript">

//write the response back to PaySecure with results of cardholder

interaction

Paysecure.sendToPaySecure(‘ISSUER100’);

</script>

ISSUER000 – Authentication was completed successfully.

ISSUER100 – Cardholder failed authentication.

ISSUER200 – Cardholder pressed 'cancel' button

ISSUER400 – Cardholder was inactive and was timed out of the session

ISSUER600 – Invalid data was posted to Issuer

ISSUER800 – General catch all error

3.5 Auth_Result After the Issuer returns the control of the iFrame to PaySecure upon successful OTP

validation i.e. on receipt of response code ISSUER000 by Paysecure, PaySecure will securely

validate with the IAS server to know the result of the authentication and mode of

authentication. This will be accomplished via the Auth_Results API call. Through this call,

PaySecure will pass “Issuer GUID” which is received in Auth_initiate response & Transaction

ID which was passed by PaySecure during Auth_initiate API call to issuer. The issuer will



respond with the result of authentication and the method used to authenticate the

cardholder.

4. Redirect - Transaction Processing

On issuer side, transaction involves two server to server API calls namely Auth_Initiate and Auth_Results and browser interaction for capturing and validating OTP on OTP page. Details of steps are provided below

4.1 Auth_Initiate The Auth_Initiate API call is used for checking card details as provided by Cardholder.

PaySecure will securely pass the card details including card number, expiry date and CVD2

along with a Hash Key (hkey) to the issuer in this call. Issuer needs to validate the card status

and mobile number status and this information can be used by issuer to determine the

available authentication method to authenticate the cardholder. HKEY will be used by IAS to

validate the hash code received from Acquirer in OTP Page re-direction request and same key

will be used to generate the hash code for the response to be send to Acquirer in response of

OTP page authentication.

In response of Auth_initiate API request the Issuer will supply Issuer Guid, URL ID, Unique

value and Cardholder ID of the authentication page, Issuer GUID, Unique Value and card

holder ID are unique values generated by issuer for each transaction and are supplied to NPCI

as part of Auth_Initiate response.

4.2 Cardholder Control by Issuer PaySecure will pass security parameters to acquirer (PG). The Acquirer will redirect to Issuer

bank authentication URL using POST method, issuer authentication URL is identified by

PaySecure using URL ID supplied by the IAS in the Auth_Initiate API call response and pass



the browser control to Issuer to complete authentication cycle. Issuer IAS system will

recognize this cardholder as one by validating the Cardholder ID data which supplied to

acquirer via PaySecure. The Issuer system will open page for authentication.

4.3 Issuer Authentication of Cardholder The Issuer now has complete control of the cardholder browser window. The issuer will

utilize this session to interact with the cardholder and authenticate based on authentication

method.

The entire browser window size is available to Issuer, find below sample illustration of the

Issuer authentication page.

Sample Issuer Page

Redirection Request Parameters:

Method: POST

Parameter Name & Type: Hidden

Parameter Name Description

AccuCardholderId Cardholder ID, Unique ID generated by Issuer which will act as session and it validate only for that particular transaction session and same that was sent by IAS in the return message during Auth Initiate API call.

AccuGuid Generated by PaySecure and same need to echo back in response

AccuReturnURL Fully qualified URL. Issuer will use to redirect the consumer upon completion of the authentication.

session To handle session, acquirer can populate value and same will be echo back in response.



AccuRequestId To avoid tampering of request data in transit, the acquirer is required to provide a hash code for the issuer to validate. This hash code can be generated by hashing TransactionID, AccuCardholderId, AccuGuid & session parameter value.

Note: Parameter Names are case sensitive

Redirection Request Form Data

1. AccuCardholderId=89172389132

2. AccuGuid=6089d50e-e012-1160-8b3b-0ab8de556755

3. AccuReturnURL=https://acquirerbank.com/support_redirect/Checkout/PinPadResult/r

edirect

4. session= CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-

2058637968!30723374!1114682342431

5. AccuRequestId - Hashing technique used will be HMACSHA256. Then IAS needs to match

hash using the same values and Key (hkey). If the hash messages do not match, the IAS is

required to decline transaction and give response code ACCU600.

Acquirer Hash Code Process for AccuRequestId in Re-direction Request

hkey : 5629y50g-e743-0022-5i2b-9aw8de632896

TransactionId : 400000000000000000000318783342

(TransactionId value to be extracted from “tran_id” parameter in Auth_Initiate

request received by Issuer)

AccuCardholderId : 89172389132

AccuGuid : 6089d50e-e012-1160-8b3b-0ab8de556755

session : CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-2058637968!30723374!1114682342431

1. Concatenate values of the request; each field is separated by the “&” symbol.

400000000000000000000318783342&89172389132&6089d50e-e012-1160-8b3b-

0ab8de556755&CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-

2058637968!30723374!1114682342431

2. Generate HMACSHA256 object using the HEKY as the pre-shared key.

3. Compute the hash of the data using this hash algorithm.

HMAC_SHA256("key", "Message")

HMAC_SHA256(“5629y50g-e743-0022-5i2b-9aw8de632896”,”400000000000000000000318783342&89172389132&6089d50e-e012-1160-8b3b-0ab8de556755&CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-2058637968!30723374!1114682342431”)

de66a13377c4f92a36c411c0a7ccd9d4ec36ca4d7a6c1e679e8c0e97f39f49dc

4. Convert the binary data to base64 encoded string. For the above binary value, the final base64

encoded string should be:



ZGU2NmExMzM3N2M0ZjkyYTM2YzQxMWMwYTdjY2Q5ZDRlYzM2Y2E0ZDdhNmMxZTY3OWU4YzBlOTdmMzlmNDlkYw==

Endpoint: https://issuerbank.com/redirect_ias/Home/IssuerReg Method : POST Request Body (url encoded):

AccuCardHolderId=89172389132&AccuGuid=6089d50e-e012-1160-8b3b-0ab8de556755&AccuReturnURL=https%3A%2F%2Facquirerbank.com%2Fsupport_redirect%2FCheckout%2FPinPadResult%2Fredirect&session=

CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-2058637968!30723374!1114682342431&AccuRequestId=ZGU2NmExMzM3N2M0ZjkyYTM2YzQxMWMwYTdjY2Q5ZDRlYzM2Y2E0ZDdhNmMxZTY3OWU4YzBlOTdmMzlmNDlkYw==

Note: ** By default, forms data is generated with URL encoding by browser engine and there is no separate URL encoding is required by Acquirer.

In order to provide a consistent ecommerce shopping experience, the bank’s logo should be

placed in the top left corner, RuPay logo should present on top right corner. Also it should

provide a cancel button on the bottom right corner. It is recommended that the issuer has to

complete the authentication process within single page and this will ensure that transaction

hops and time wont increased.

4.4 Cardholder Return Browser Control Redirection Response Parameters:

Method: POST

Parameter Name & Type: Hidden

Parameter Name Description

AccuResponseCode Code that provides authentication status to drive business rules on how to process the consumer transaction. This data will be POST to URL of the AccuReturnURL.

session To handle session, Issuer/PaySecure will send whatever value received in request, same value will be sent in response. This data will be POST to URL of the AccuReturnURL.

AccuGuid Issuer will be echo back in response. This data will be POST to URL of the AccuReturnURL.

AccuRequestId To avoid tampering of response data in transit, the issuer is required to provide a hash code for the acquirer to validate. This hash code can be generated by hashing TransactionID, AccuGuid, session & AccuResponseCode parameter value.

Note: Parameter Names are case sensitive

*Please ensure that no custom variables are prefixed with “ACCU” as those are reserved for RuPay.



Note: Request & Response parameter name are case sensitive.

Redirection Response Form Data

1. AccuGuid=6089d50e-e012-1160-8b3b-0ab8de556755

2. session= CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-

2058637968!30723374!1114682342431

3. AccuResponseCode=ACCU000

4. AccuRequestId - Hashing technique used will be HMACSHA256. Then Acquirer needs to

match hash using the same values and Key (hkey). If the hash messages do not match, the

acquirer is required to decline transaction and do not proceed further with authorization

request to NPCI.

Issuer Hash Code Process for AccuRequestId in Re-direction Response

hkey : 5629y50g-e743-0022-5i2b-9aw8de632896

TransactionId : 400000000000000000000318783342

(TransactionId value to be extracted from “tran_id” parameter in Auth_Initiate

request received by Issuer)

AccuGuid : 6089d50e-e012-1160-8b3b-0ab8de556755

session : 318723982

AccuResponseCode : ACCU000

1. Concatenate values of the request; each field is separated by the “&” symbol.

400000000000000000000318783342&6089d50e-e012-1160-8b3b-

0ab8de556755&CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GU

mi!-2058637968!30723374!1114682342431&ACCU000

2. Generate HMACSHA256 object using the HEKY as the pre-shared key.

3. Compute the hash of the data using this hash algorithm.

HMAC_SHA256("key", "Message")

HMAC_SHA256(“5629y50g-e743-0022-5i2b-9aw8de632896”,”400000000000000000000318783342&6089d50e-e012-1160-8b3b-0ab8de556755&CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-2058637968!30723374!1114682342431&ACCU000”)

f820b0c71cb65c89239e2a0a717066723fbeb74fef9795be308f3929cddeb5d4

4. Convert the binary data to base64 encoded string. For the above binary value, the final base64

encoded string should be:

ZjgyMGIwYzcxY2I2NWM4OTIzOWUyYTBhNzE3MDY2NzIzZmJlYjc0ZmVmOTc5NWJlMzA4ZjM5MjljZGRlYjVkNA==



Endpoint: https://issuerbank.com/redirect_ias/Home/IssuerReg Method : POST Request Body (URL encoded):

session= CwzmsrQN2f15faUUOmHIHkGefRcg8BgHPnvx9E3pW7MNkwC6GUmi!-2058637968!30723374!1114682342431&AccuResponseCode=ACCU000&AccuGuid=6089d50e-e012-1160-8b3b-0ab8de556755&AccuRequestId=ZjgyMGIwYzcxY2I2NWM4OTIzOWUyYTBhNzE3MDY2NzIzZmJlYjc0ZmVmOTc5NWJlMzA4ZjM5MjljZGRlYjVkNA==

Note:

** By default, forms data is generated with URL encoding by browser engine and there is no separate URL encoding is required by Issuer.

** Sequence of parameters in hashing input, will be same as given in example.

** Acquirer & Issuers are strongly recommended not to pass/use/communicate secrete Hash Key i.e. hkey & TransactionID in any way over browser communication or to any third party.

** Acquirer & Issuers are liable to manage the secrecy of Hash Key i.e. hkey & TransactionID at their respective environment/infrastructure. Redirection Authentication page request URL: Issuer Bank authentication page URL will

be configured into PaySecure system at time of bank on boarding and against that URL,

unique URL ID tag will be generated by PaySecure and shared with respective member bank.

IAS has to send the same URL ID in the successful response of auth initiate API call and on the

basis of same redirection of cardholder for the authentication will take place.

Example

Issuer Bank Authentication Page URL URL ID generated by PaySecure

https://issuerbank.com/redirect_ias/Home/Iss

uerReg

30e08bba-6f9c-4e8d-944a-

c882172630c0

Authentication Response Status Code

Resp Code Description Required Action

ACCU000 PIN collected / Authentication completed Move to Authorization (Authorize API Call)

ACCU100 Authentication Failed Decline transaction ACCU200 Cardholder pressed Cancel button Decline transaction ACCU400 Cardholder inactivity timeout Decline transaction ACCU600 Invalid Data received posted Decline transaction ACCU700 Duplicate Data posted or Session already

expired Decline transaction

ACCU800 General Error Encountered Decline transaction

https://issuerbank.com/redirect_ias/Home/IssuerReg

https://issuerbank.com/redirect_ias/Home/IssuerReg



Once the cardholder has completed the Issuer authentication, the Issuer has to return

browser control back to AccuReturnURL. The Issuer will return control of the cardholder via

browser/app to Acquire/PaySecure using POST method.

4.5 Auth_Result Once Issuer returns the control, acquirer PG server will send Authorize API call to PaySecure

server. On receipt of this call, PaySecure server will securely validate with the IAS server to

know the results of the authentication and mode of authentication. This will be accomplished

via the Auth_Results API call. Through this call, PaySecure will pass “Issuer GUID” send by

issuer in response of Auth_Initiate API call & Transaction ID which was passed by PaySecure

during Auth_Initiate API call to issuer. The issuer should respond with the result of

authentication and the method used to authenticate the cardholder. On successful

authentication response from IAS, PaySecure forward the ISO message request to Issuer

Switch.

*On receipt of successful response for Auth_Result API call from Issuer, authentication will be considered successful for the respective transaction.

5. Transaction ID In request of Auth_Initiate API & Auth_Results API call, PaySecure sends Transaction ID to IAS

which is unique for each transaction and the same transaction id would also be supplied to

the issuer bank switch in the Online ISO message in data element 48 tag 61.

6. Time out scenarios and handling The various timeout scenarios fall into the following categories:

6.1 PaySecure-to-Issuer (during Auth Initiate API) a. PaySecure sends Auth_Initiate API call to know the available authentication of

the cardholder.

b. PaySecure will wait for 10 seconds for a response from the Issuer.

c. PaySecure will treat this timeout as a negative-authentication and respond the

acquirer with error code indicating that the Issuer Authentication Failure.

6.2 Cardholder-to-Issuer (during cardholder interaction) a. PaySecure passes iFrame/redirection control to issuer (IAS) for cardholder

authentication.

b. Iframe Flow/Redirection Flow, IAS will maintain 5 minute wait time to allow

cardholder to complete the authentication process and will return control with

code ISSUER400 for Iframe flow and ACCU400 for redirection flow in the event

where the cardholder authentication exceeds that maximum threshold time.

c. PaySecure will treat this timeout as a negative authentication indicating that

the authentication was not successful.



6.3 PaySecure-to-Issuer (during Auth_Results API) a. PaySecure sends Auth_Result API call to know the result of authentication and

mode of authentication.

b. PaySecure will wait for 10 seconds for a response from the Issuer.

c. PaySecure will treat this timeout as a negative-authentication indicating that

the authentication was not successful.



6.4 Time Out Details

PaySecure to Issuer Authentication Server (IAS)

Sr Process Step Entity Max

Response Time

Remarks

1 Auth Initiate PaySecure to Issuer

Authentication Server 10 seconds

PaySecure will close connection the after 10 seconds timeout

2 Auth_Results PaySecure to Issuer


PaySecure will close connection the after 10 seconds timeout

3 Cardholder Interaction

Cardholder Browser to Issuer


Ideal timeout on authentication page (5 Minutes)

7. System Security Features

The following security measures should be considered at Issuer Authentication Server.

7.1 Issuer Authentication methods

1. UserID(IWS)

2. Password(IWS)

Issuer web service calls (IWS)

7.1.1 User ID (IWS) Unique User ID is created by Issuer and same will be configured at PaySecure.

Assigned by the issuer during the on-boarding process and will allow Issuer

bank to change at any point of time based on bank request with proper process

at NPCI end.

Whenever User ID is changed, it is mandated to the change password also.

PaySecure will send this user id in Auth_Initiate/ Auth_Results API call.

Issuer will validate the user id for Auth_Initiate/ Auth_Results API call before

proceeding with request process.

7.1.2 Password (IWS) Password is created by Issuer and same will be configured at PaySecure.

The password that corresponds to the user id to validate the authenticity.

Assigned by the issuer during the on-boarding process and will allow Issuer

bank to change at any point of time based on bank request with proper process

at NPCI end.

PaySecure will send this password in Auth_Initiate/Auth_Results API call.



Issuer will validate the password for Auth_Initiate/ Auth_Results API call.

Password formation should follow the basic password policy i.e. minimum

length should be 8 digit and should contain at least 1 upper case, 1 lowercase, 1

numeric, 1 special symbol.

7.2 Transport Security

RuPay eCommerce solution (PaySecure) messages depends on the confidentiality of transport security. Before sending a data message between PaySecure and Issuer components, the channel over which the message is transmitted must be secured through the establishment of an SSL session using a TLS/SSL Server Certificate.

7.3 Cardholder/ Shopper Browser Authentication Methods

Issuer authenticates the cardholder browser using Cardholder ID (Unique ID generated by Issuer for each transaction which will act as session and it validate only particular transaction) that was sent by IAS in the response of secure Auth Initiate API call.

7.4 Separation of Card details/PAN and OTP authentication mechanism

In this model, data related to the authentication key field like OTP, PIN, User ID & Password and Data related to the card number/ PAN is collected via separate channels.

This is done for two reasons:

The acquirer is never given access to the Cardholder’s registered mobile number or the

dynamic OTP being sent to customer. The acquirer has no need to access this data and if

the acquirer has been compromised by an unrelated attack, only card number data will

be compromised.

NPCI is never given access to actual OTP being sent to customer as there is no need for

NPCI to access this information. Even after successful authentication, only a response

from IAS is received which is stored against the transaction, neither mobile number nor

the OTP.

7.5 Web Application Firewall NPCI deploys Web Application Firewall for the communication of Cardholder and Acquirer Channels with NPCI to filter unauthorized request and access. All traffic to NPCI is scanned against a specific set of rules and criteria within the Web Application Firewall.

8. Integration Requirements



Integrating the PaySecure process into the Issuer Authentication system involves the

following points:

8.1 Connectivity to NPCI’s PaySecure product SOAP 1.1 or higher Web Services

8.2 Connectivity to NPCI’s PaySecure product

8.2.1 Web Service Security

When PaySecure connects to Issuer during API Call interaction, Issuer will verify

authenticity of request from PaySecure using User Id and Password which is pre-

configured at the time of on boarding bank in PaySecure.

8.2.2 URLs

PaySecure will be connecting to Issuer Authentication system via internet through

cardholder browser and all data will encrypt using SSL/TLS. Issuer bank domain

URL (WSDL & Authentication Page URL) should have public access on port 443 and

bind with SSL/TLS certificate which should be globally accepted like Verisign,

Symantec and etc.

9. Web-Services API Call & Example

Web Services provides a simple interface for communicating with PaySecure. Following web-

services are provided by Issuer for PaySecure to invoke:

1. Auth_Initiate

2. Auth_Result

This web service hosts a method to execute commands and is designed to receive and return

XML formatted data. The web service method is represented below:

Object Description

Web Service Web Service reference that interfaces the Channel

commands.

Method Description

CallPaySecure (command, xml

input)

This method executes the supplied command (i.e.

Auth_Initiate, Auth_Results) with its XML defined

input parameters. The xml input must be html

encoded.

Example: The XML tags for the input and output of these methods is the same as the input and output parameter names of the commands in the following section. The root node XML tag is <paysecure>. All input and output parameters are child node of the <paysecure> node. And



the XML message header part should contain “Content-Length=xxxx” which means xxxx bytes are being posted, should not use “Transfer-Encoding = chunked” method.

9.1 Auth_Initiate API Call

This command allows PaySecure to begin the Cardholder Authentication process with the

issuer authentication server (IAS).

Auth_Initiate API

Request

**

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<RequestorCredentials

xmlns="https://paysecure/merchant.soap.header/">

<Version>1.0.0.0</Version>

<UserCredentials>

<UserID>[email protected]</UserID>

<Password>Password!1</Password>

</UserCredentials>

</RequestorCredentials>

</soap:Header>

<soap:Body>

<CallPaySecure xmlns="https://paysecure/merchant.soap/">

<strCommand>Auth_Initiate</strCommand>

<strXML><paysecure><card_no>6076000000000048&lt

;/card_no><card_exp_date>122020</card_exp_date><car

d_holder_status>NW</card_holder_status><cvd2>320</

cvd2><language_code>EN</language_code><tran_id>

100000000000000000000318717660</tran_id><hkey>

5629y50g-e743-0022-5i2b-9aw8de632896

</hkey></paysecure></strXML>

</CallPaySecure>

</soap:Body>

</soap:Envelope>

Response

##




<soap:Body>

<CallPaySecureResponse

xmlns="https://paysecure/merchant.soap/">

<CallPaySecureResult><paysecure><Issuer_Guid>bf44f06e-

ebd6-40b5-a826-509e60498bdf</Issuer_Guid><Url_ID>3563a1f0-



f918-4902-9569-

d1c5879eefeb</Url_ID><Cardholder_id>89172389132</Cardhol

der_id><Unique_value>714040</Unique_value><Errorcode&g

t;00</Errorcode></paysecure></CallPaySecureResult>

</CallPaySecureResponse>

</soap:Body>

</soap:Envelope>

**Please pay attention to the bold text in the request. The value in the “strXML” tag must be

html encoded. (i.e.: The “<” symbol is represented by “<” and “>”symbol is represented by

“>”)

##The response is made up of various elements and in order to determine the success of

Auth_Initiate API call, element considered is <errorcode>. This element should return a ‘00’ to

indicate that card number and mobile number availability at IAS end is verified and

authentication process for card can be continued.

9.2 Auth_Results API Call

This API call allows PaySecure to securely query the Issuer Authentication Server results.

Auth_Results API

Request

**

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:mer="https://paysecure/merchant.soap.header/"

xmlns:mer1="https://paysecure/merchant.soap/">

<soapenv:Header>

<RequestorCredentials xmlns="https://paysecure/merchant.soap.header/">

<Version>1.0.0.1</Version>

<UserCredentials>

<UserID>[email protected]</UserID>

<Password>Password!1</Password>

</UserCredentials>

</RequestorCredentials>

</soapenv:Header>

<soapenv:Body>

<CallPaySecure xmlns="https://paysecure/merchant.soap/">

<strCommand>Auth_Results</strCommand>

<strXML><paysecure><guid>93f594ca-ddc5-4e70-

9b57-

8b0a1370d1a9</guid><shopper_ip_address>115.242.37.201&l

t;/shopper_ip_address><shopper_country_code>356</shopper_

country_code><tran_id>100000000000000000000000025236<

/tran_id></paysecure></strXML>

</CallPaySecure>



</soapenv:Body>

</soapenv:Envelope>

Response

##




<soap:Body>

<CallPaySecureResponse xmlns="https://paysecure/merchant.soap/">

<CallPaySecureResult><paysecure>

<auth_method>OTP</auth_method>

<status>SUCCESS</status><errorcode>00</errorcode>&lt

;/paysecure>

</CallPaySecureResult>

</CallPaySecureResponse>

</soap:Body>

</soap:Envelope>

**Please pay attention to the bold text in the request. The value in the “strXML” tag must be

html encoded. (i.e.: The “<” symbol is represented by “<” and “>”symbol is represented by

“>”)

##The response is made up of various elements but to determine the success of Auth_Results

API call, two elements are considered. First element to consider is <status>, this tag is used to

let the requester know if authentication of cardholder for the respective transaction was

successful at IAS end and IAS will return a success or failure basis the status of Authentication.

The second element to consider is the <errorcode> element. This element will return a ‘00’ to

indicate that authentication of cardholder for the respective transaction was successful at IAS

end.

Only in case of successful authentication at IAS end, IAS will respond with status as “SUCCESS”

and error code as ‘00’.

10. Issuer Authentication Server

Issuer bank would be responsible to create & host the Web Service and web pages for card

holder authentication process, web page should be responsive to properly fit into desktop,

mobiles and tablets screen size.

Note: “Mobile number details recommended to be maintained on IAS so that Issuer switch won’t

be queried each time for every transaction to fetch the mobile number details.”

11. Member bank pre-requisites & Issuer On-Boarding

11.1 Member bank pre-requisites



The following pre-requisite needs to be adhered before applying for the RuPay e-Commerce

process:

1. Bank should issue RuPay Debit/Credit card and process authorize transaction.

2. Bank’s issuing switch should be certified with NPCI switch for eCommerce transaction

processing.

3. Issuing bank should have the capability to authenticate the cardholder over the web

channel. A typical Issuer Authentication Server (IAS) is required for this purpose.

4. The institution should have applied for membership in NPCI’s RuPay card scheme as

Issuer.

5. The member should have a test system to complete the testing and/or certification for

e-Commerce before moving to the production system. The member should not carry

out any testing in the production system.

6. The member should not be part of any negative credit report by the rating agencies /

regulatory authorities

7. The member should have a dedicated team and system to undertake testing,

certification and audit of the system

11.2 Issuer On-Boarding Issuer is required to submit the details in the form specified by NPCI (called on-boarding

form) for issuer on boarding in the PaySecure system. In response to this on boarding form

NPCI will supply security parameters & URL ID to the issuer. Issuer needs to send this

security data during the API call.

12. Best Practices

12.1 Transaction Review and Filtering 1. Amount Filter – Uses lower and upper transaction amount thresholds to restrict high-

risk transactions.

2. Velocity Filter – Limits the total number of transactions received per hour/day,

preventing high-volume attacks common with fraudulent transactions.

3. Shipping Billing Mismatches – Identifies high-risk transactions with different shipping

and billing addresses, potentially indicating fraudulent transactions.

4. Transaction IP Velocity – Isolates suspicious activity from a single source by

identifying excessive transactions received from the same IP address.

5. Suspicious Transaction Filter – Review highly suspicious transactions using criteria

identified as being indicative of fraud or known to be fraud. One example is the lists

available that contain known shipping addresses of fraudsters.

6. IP Address Blocking – Blocks transactions from IP addresses known to have been used

in fraudulent activity.

12.2 Network and Infra Security 1. Install a firewall - A firewall is a hardware or software solution that monitors the

activity of external connections (primarily the internet) to an internal network of



servers. Firewalls help to eliminate unauthorized or unwanted external activity and

safeguard your network and connections from outside threats.

2. Store all sensitive or confidential information separate from web servers.

3. Use Anti-Virus Software and Update It regularly.

4. Regularly Download and Install Security Updates.

5. Avoid Sending or Requesting Confidential Information via Insecure Methods.

12.3 Adhere to the PCI Data Security Standard Requirements The Payment Card Industry (PCI) Data Security Standard is an industry-wide program

designed to significantly increase security for storing, transmitting, and processing

cardholder data. To maximize security, it is recommended that the Member Banks thoroughly

review and adhere to PCI requirements.

12.4 Suspicious transactions to be monitored: 1. New customer: Since fraudsters generally look for newer merchants for fear of

identification.

2. Unusual size of purchase: Because of the need to maximize value of transaction due to

limited life-span of stolen card

3. Suspicious quantities of the product purchased: If more than normal quantities of an

item are purchased, it might indicate a counterfeit or lost/stolen card

4. Items with maximum resale value form the majority of the purchases: Fraudsters are

looking with high value items which also have a very high resale value

5. Inclination towards speedy shipping/readiness to pay unusual shipping charges:

Fraudsters want quick delivery to avoid getting caught or their address traced.

6. International shipping: This is generally a high risk transaction

7. Patterns in account numbers used for transactions (e.g.: transactions using

consecutive/similar account numbers): These indicate usage of software-generated

account numbers

8. Transactions through multiple cards getting shipped at the same address, or multiple

transactions on one card over a very short period of time, or multiple card transactions

from the same billing address but to different shipping addresses or transactions using

multiple cards, but from the same IP address. The fraudster might be making a high

amount of small purchases though different counterfeit cards/addresses to evade

detection

12.5 Cardholder acquisition A cardholder is an individual with a valid account number who has been issued a payment

card by the issuing bank.

Cardholder acquisition is the first step in the payment process and thus it is essential that due

care be taken to implement preventive measures against fraud at this stage. The issuer should

follow the guidelines mentioned below to reduce risk of losses due to application frauds.



Ensure Know Your Customer (KYC) norms are met for the cardholder’s account before

issuance of card.

The customer must provide his/her legal name and any other names used

The bank must ask for an address proof/proof of residence

Telephone bill

Bank account statement

Letter from any recognized public authority

Electricity bill

Ration card

Letter from employer (subject to satisfaction of the bank)

The account holder must present a valid photo identification

Passport

PAN card

Voter’s Identity Card

Driving license

Identity card like UID (subject to the bank’s satisfaction)

Letter from a recognized public authority or public servant verifying the identity

and residence of the customer (subject to the satisfaction of bank)

The account opening process must be aligned with the issuance of debit cards

simultaneously.

Effective application fraud screening practices must be implemented. e.g. comparing

application data with bank customer data and credit bureau reports

Decline direct-mail applications that have been substantially altered or submitted by

anyone other than the intended party

Implement “closed-loop” feedback process involving all members of the payment chain

to identify characteristics of fraudulent applications and develop preventative

measures for the same

12.6 Drafts SMS’s Suggested for Issuer

1. Transaction failure message drafts: (Can be used by merchants/Issuers- Optional) Sorry! Your e-commerce transaction using bank name RuPay card XXXX1234 was

unsuccessful. Please try again. Your e-commerce transaction using bank name RuPay card XXXX1234 was

unsuccessful. Please contact our customer service.

2. OTP received message drafts: ****** is the One Time Password (OTP) for your transaction using RuPay Card

XXXX1234. This can be used one time only and it is valid for 15 min. Your OTP for e-Commerce transaction using Bank Name RuPay Card XXXX1234 is

****** and it’s valid for 15 min. Bank Name OTP is ******



This is to be used for online transaction using RuPay card XXXX1234 and it is valid for 10 min.

3. Successful Transaction & debiting amount from the customer’s a/c Thanks for using your Bank name RuPay Card XXXX1234 for Rs. XXX towards e-

Commerce transaction at Merchant. – Here ‘e-Commerce’ is optional. But Merchant name should be mandatorily mentioned in the SMS text.

Rs. XXX is debited from your A/C for using your RuPay Bank name Debit Card XXXX1234 for online transaction at Merchant- Here ‘e-Commerce’ is optional. But Merchant name should be mandatorily mentioned in the SMS text.



Annexures A - Message Format

Auth Initiate

Auth_Initiate() - command allows PaySecure to begin the Card-Holder Authentication process.

PaySecure sends to Issuer Authentication Service

Input

Parameters

Requ

ired

Type

(Length) Format

Possible

Values Contents

SOAPHeader –

version M ANS(7-32) Variable

Static assigned

by PaySecure

The current version of

PaySecure system.

SOAPHeader –

userid M

ANS(1-

256) Variable

Static assigned

by Issuer

An ID assigned by the issuer

to identify PaySecure.

SOAPHeader –

password M ANS(8-36) Variable

Static assigned

by Issuer

A password that

corresponds to the user ID

assigned by the issuer.

SOAPBody -

card_no M N(13-19) Variable

Full length card

number as

embossed on

card

The full length card number,

(PAN), as entered on the

Merchant website by the

cardholder.

SOAPBody -

card_exp_date M N(6) Fixed MMYYYY

The month and year the

card expires as entered on

the merchant website by the

cardholder.

SOAPBody –

cvd2 M N(3-4) Variable

CVD2 as

displayed on

card

The CVD2 as entered by the

cardholder on the

merchant’s website.

SOAPBody -

card_holder_st

atus

M AN(2) Fixed NW

Fixed Value, Reserved for

future purpose

SOAPBody -

language_code M AN(2-5) Variable

EN only –

potential for

additional

languages in

future

Language code used to drive

the language on the Issuer

Authentication pages.

SOAPBody -

tran_id M N(30) Fixed Transaction ID

A unique ID assigned by

PaySecure to the each

transaction and remains

constant throughout the

lifecycle of the transaction.

SOAPBody –

hkey M ANS(36) Fixed Hash Key

A unique hash key assigned

by PaySecure to each



transaction to be used by

IAS for generating the hash

code for re-direction

authentication response.

Outputs

issuer_guid C ANS(36) Fixed GUID

Unique id for each

transaction assigned by the

issuer to the transaction and

will be used for the life of

the authentication process.

For decline transaction

issuer guid should not be

populated.

url_id C ANS(36) Fixed url identifier

Predefined identifier that

corresponds to a preloaded

base url in the PaySecure

system. This is a lookup id.



populated.

cardholder_id C AN(0-36) Variable

Cardholder_ID that

identifies the session and

same will be passed during

authentication page via

cardholder interaction. IAS

should generate unique

value for each tranaciton,

which will act as session.

Iframe – GET Method

This will be appended to the

end of the url in the

following form:

https://www.abc.com/auth

Page?ID=[cardholder_id]

Redirection – POST Method

This value will be one the

parameter in POST method.

https://www.abc.com/auth

Page

https://www.abc.com/authPage?ID=%5bcardholder_id

https://www.abc.com/authPage?ID=%5bcardholder_id

https://www.abc.com/authPage

https://www.abc.com/authPage





populated.

Errorcode M N(0-4) Variable

See Error Codes

/ Messages for

details

This is a numeric code used

to provide success or failure

response

unique_value C ANS(40) Variable

Unique Value returned by

Issuer Authentication

Server. This will be passed

to Issuer switch in ISO

message. This can be used

by issuing bank to match the

authentication status of

transaction at IAS end.

M – Mandatory; O – Optional; C – Conditional

Note: All conditional values along with ‘error_code’ are used to determine Auth_Initiate

success.

Auth_Results

Auth_Results() - command allows PaySecure to securely query IAS for cardholder

Authentication result.

PaySecure sends to Issuer Authentication Service

Input

Parameters

Requ

ired

Type

(Length) Format

Possible

Values Contents

SOAPHeader –

version M ANS(7-32) Variable

Static assigned

by PaySecure

The current version of

PaySecure System.

SOAPHeader –

userid M

ANS(1-

256) Variable

Static assigned

by Issuer

An ID assigned by the issuer

to identify PaySecure

SOAPHeader –

password M ANS(8-36) Variable

Static assigned

by Issuer

A password that

corresponds to the userID

assigned by the issuer.

SOAPDetail –

guid M ANS(36) Fixed GUID

Unique id for each

transaction assigned by the

issuer to the transaction and

will be used during the life

cycle of the authentication

process.

shopper_ip_ad

dress M ANS(39) Variable

Shopper browser IP address

shopper_count M N(3) Fixed Country code

based on IP

Refer to ISO 3166 for



ry_code address of

shopper

browser

country code list.

tran_id M N(30) Fixed Transaction ID

A unique ID assigned by

PaySecure, to the

transaction and remains

constant throughout the

lifecycle of the transaction.

Outputs

auth_method M AN(0-16) Variable

OTP – One

time password

OLB – Online

banking

credentials

CR – Challenge

Response

question

VR – Voice

Recognition

BIO -

Biometric

PKI – Public

Key

Infrastructure,

User

confirmed via

a certificate

TTP - Trusted

Third Party

validated user

The authentication method

used by the Issuer to

validate the cardholder.

Status M A(7) Fixed SUCCESS /

FAILURE

Issuer has to send either

success / Failure, that

indicates status of

authentication carried out

by IAS

errorcode M N(0-4) Variable

See Error

Codes /

Messages for

details

This is a numeric code used

to provide success or failure

response.

Note: ‘Status’ and ‘errorcode’ are used to determine Auth_Results success



Redirection Request Parameter

Method: POST Parameter Name & Type: Hidden

Parameter Name Required

Length Format Description

AccuCardholderId M 36 (ANS) Variable Extract value from Initiate2 API Response in RedirectURL tag.

AccuGuid M 36 (ANS) Variable Extract value from Initiate2 API Response in RedirectURL tag.

AccuReturnURL M 512 (ANS) Variable Acquirer has to provide URL to which authentication status will be sent by Issuer.

session M 1024 (ANS) Variable To maintain and retrieve the transaction at acquirer end, Session value will be echo back in response.

AccuRequestId M 128(ANS) Variable To avoid tampering of request data in transit, the acquirer is required to provide a hash code for the issuer to validate. This hash code can be generated by hashing TransactionID, AccuCardholderId, AccuGuid & session parameter value.

Redirection Response Parameter

Method: POST Parameter Name & Type: Hidden

Parameter Name Required Length Format Description

AccuResponseCode M 10(AN) Variable Authentication status code will be sent by Issuer/PaySecure

session M 1024 (ANS) Variable Same value should be send in response without any modification.

AccuGuid M 36 (ANS) Variable Same value will be send in response without any modification and it helps to



match request & response.

AccuRequestId M 128(ANS) Variable To avoid tampering of response data in transit, the issuer is required to provide a hash code for the acquirer to validate. This hash code can be generated by hashing TransactionID, AccuGuid, session & AccuResponseCode parameter value.



Annexures B - Error Code/messages

1. Error Codes / Status Codes For Auth_Initiate

Error Code Description Reference XML Tag

00 Card details & Mobile no status validation successful

Entire SOAP envelop along with values of parameters passed

IAS has to successfully complete all technical as well as business validations on XML structure and values of all the parameters as present within tag to return code '00'

Comments It also may be noted that in case of Auth_Initiate success is determined on basis of <error code> element only

01 Missing Parameter

Entire SOAP envelop along with values of parameters passed IAS has to check all the parameters and if any of the required parameter is not present then return this error code

02 Invalid Command

<strCommand> IAS checks if command in this tag is as per specs and if not will decline with this reason code

14 Card no error <strXML> IAS has to check all the parameters and if Card_no is not valid then return this error code

42 No acccount <strXML> IAS has to check all the parameters and if Card_no and account is not linked at banks core banking then return this error code

54 Expired Card <strXML> IAS has to check all the parameters and if card is expired it should return this value

56 No Card <strXML> IAS has to check all the parameters and if Card_no is not present at IAS return this error code

59 Fraud/Hot Listed Card

<strXML> IAS has to check all the parameters and if Card_no is present but hot listed at IAS then return this error code

62 Restricted Card <strXML> IAS has to check all the parameters and if Card_no is present but use of card is not allowed on ecommerce channel for any reasons as decided by IAS then return this error code

94 Duplicate Transaction

<strXML> Using Tran ID IAS to validate if same transaction has already processed by IAS in past, then return this error code

96 System Error In case if due to any technical error IAS is unable to process transaction then IAS to return this error code

399 System Unavailable

In case if interfacing systems are unavailable at IAS end, like CBS, for some reasons resulting in non-processing of transaction then IAS to return this error code

400 General Error If IAS is not able to process transactions for codes as specified in this document then IAS can return this code



401 Command is Null or Empty

<strCommand> IAS checks tag and if NULL or Empty command found, then decline with this reason code

402 XML is Null or Empty

<strXML>, If XML body in this tag is Null or Empty then return this message

406 Not Authenticated

<UserID> and <Password> IAS has to check under SOAP header and validate User ID and Password if not match then IAS to return this error code

407 Not Authorized IAS to check source IP and if source IP is not from white listed IP addresses at application level then IAS to return this error code

408 XML Data Error Entire SOAP envelop along with values of parameters passed IAS to validate entire XML structure/format and if validation fails then IAS to return this error code

410 Invalid BIN <strXML> IAS has to check all the parameters and if Card_no is from BIN range which is not available at IAS then IAS to return this error code

411 Ineligible PAN/Mobile number not present

<strXML> IAS has to check all the parameters and if for Card_no, mobile number is not present then IAS to return this error code

413 Invalid CVD2 <strXML> IAS has to check all the parameters and if CVD2 value is not validated successfully then IAS to return this error code

414 Expiry Date Mismatch

<strXML> IAS has to check all the parameters and if Card_Expiry_Date for Card_no is not matching with master data present at IAS then return this error code

2. Error Codes / Status Codes For Auth_Results

Error Code Description Reference XML Tag

00 Authentication Successful

Entire SOAP envelop along with values of parameters passed IAS has to succefully complete all technical as well as busines validations on XML structure and values of all the parameters as present within tag to return code '00' Comments

Redirect: 1. OTP validated successfully 2. ACCU000 in AccuResponseCode

I-Frame: 1. OTP validated successfully 2. ISSUER000 to cardholder browser.



It also may be noted that in case of Auth_Results success is determined on basis of two elements <status> and <error code>

01 Missing Parameter

Entire SOAP envelop along with values of parameters passed IAS has to check all the parameters and if any of the required parameter is not present then return this error code

02 Invalid Command

<strCommand> IAS checks if command in this tag is as per specs and if not will decline with this reason code

59 Fraud/Hot Listed Card

<strXML> IAS has to check all the parameters and if Card_no is present but hot listed at IAS then return this error code

62 Restricted Card

<strXML> IAS has to check all the parameters and if Card_no is present but use of card is not allowed on ecommerce channel for any reasons as decided by IAS then return this error code

63 Authentication Mismatch _Attempted frauds

<strXML> Using Tran ID and Issuer GUID, IAS to validate/verify the authentication result and authentication method used Comment Redirect: Any of below message send in AccuResponse code ACCU100/200/400/600/700/800 or No authentication request from cardholder browser or Any other scenarios whereby authentication cannot be ascertained I-Frame: Any of below messages are send to browser ISSUER100/200/400/600/800 or No authentication request from cardholder browser or Any other scenarios whereby authentication cannot be ascertained

94 Duplicate Transaction

<strXML> Using Tran ID and Issuer GUID IAS to validate if same transaction has already processed by IAS in past, then return this error code

96 System Error In case if due to any technical error IAS is unable to process transaction then IAS to return this error code

399 System Unavailable

In case if interfacing systems are unavailable at IAS end, like CBS, for some reasons resulting in non-processing of transaction then IAS to return this error code

400 General Error If IAS is not able to process transactions for codes as specified in this document then IAS can return this code

401 Command is Null or Empty

<strCommand> IAS checks if command in this tag is as per specs and if NULL or Empty command found, then decline with this reason code



402 XML is Null or Empty

<strXML>

If XML body in this tag is Null or Empty then return this message

406 Not Authenticated

<UserID> and <Password> IAS has to check under SOAP header and validate User ID and Password if not match then IAS to return this error code

407 Not Authorized

IAS to check source IP and if source IP is not from white listed IP addresses at application level then IAS to return this error code

408 XML Data Error

Entire SOAP envelop along with values of parameters passed IAS to validate entire XML structure/format and if validation fails then IAS to return this error code

415 Lost Card <strXML> IAS has to check all the parameters and if Card_no is present but same is flagged as lost card at IAS then return this error code

416 Stolen Card <strXML> IAS has to check all the parameters and if Card_no is present but same is flagged as stolen card at IAS then return this error code

3. Response Codes For I-Frame

Response Code Status Description

ISSUER000 Success Authentication successfully.

ISSUER100 Failure Cardholder failed authentication.

ISSUER200 Failure Cardholder pressed 'cancel' button

ISSUER400 Failure Cardholder was inactive and was timed out of the session

ISSUER600 Failure Invalid data was posted to Issuer

ISSUER800 Failure General excpetion

ISSUER999 Acknowledgement Modal popup was opened successfully

4. Response Codes For Redirect

Response Code Status Description

ACCU000 Success Authentication Successful

ACCU100 Failure Authentication Failed

ACCU200 Failure User Pressed 'cancel' button

ACCU400 Failure User was Inactive

ACCU600 Failure Invalid data was posted to Issuer

ACCU700 Failure Session validation failed

ACCU800 Failure General excpetion

rupay- paysecure issuer integration guide version 1.6 14 ... · rupay issuer integration guide...

Documents