Integration Guidelines
Supported Features (Security)
RuPay Payer Authentication
Implementing RuPay Authentication using Authentication API

Implementing RuPay Authentication using Authentication API

This page describes how to integrate to the gateway to use RuPay authentication using the Authentication API.

RuPay Authentication Flow

The diagram below illustrates the authentication flow for a payment where the payer is authenticated using RuPay PaySecure.

RuPay Authentication Flow

The authentication flow for a successful RuPay authentication is as follows:

A payer browses your shop site, selects one or more products, proceeds to the payment page, and selects to pay with a RuPay card that supports RuPay PaySecure.
Initiate Authentication: You ask the gateway to check with RuPay PaySecure if the card is eligible for RuPay payer authentication.
If RuPay authentication of the payer is available, the gateway returns the authentication details in the response.
Authenticate Payer: You ask the gateway to perform the initiated authentication. Invoke this when the payer clicks the 'Pay Now' button on the checkout page.
The gateway returns the redirect URL and the RuPay authentication Transaction ID from RuPay PaySecure in the Authenticate Payer response.
You redirect the payer’s web browser to the issuer, where the payer validates their OTP. The issuer returns the authentication result to the gateway. The gateway redirects the payer directly to your website.
Use the RuPay Authentication Transaction ID in a Payment Operation: You submit the payment for processing.
You display the order confirmation page to the payer.

Integrating to use RuPay Payer Authentication

This section describes how to integrate to the gateway to use RuPay Payer Authentication.

Step 1: Initiate Authentication

The Initiate Authentication operation is used to determine if RuPay payer authentication is available to the merchant for a given card. If the card type is RuPay, the gateway determines the eligibility of the RuPay card BIN for eCommerce transactions.

Initiate Authentication API Reference [REST] [NVP]

Initiate Authentication Request

You can initiate RuPay authentication by providing the following fields in the Initiate Authentication request:

session.id or sourceOfFunds.provided.card or sourceOfFunds.token: Details of the card being used for the payment
order.currency: The currency of the order.
transaction.id: A unique identifier for this payment authentication.
order.id: A unique identifier for this order.

Initiate Authentication Response

If RuPay payer authentication is available, the gateway returns authentication.version=RUPAY, and the following fields:

response.gatewayCode
transaction.authenticationStatus: Provides more details about the authentication status.
result
response.gatewayRecommendation

To determine the next step, check the gateway's recommendation provided in the response.gatewayRecommendation field.

`response.gatewayRecommendation`	Next step
PROCEED	You can proceed to authenticate the payer using the Authenticate Payer operation.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	Ask the payer for alternative payment details (For example, a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request.

The following table shows the Initiate Authentication response for the various Rupay authentication scenarios.

State	`response.gatewayRecommendation`	`transaction.authenticationStatus`	`response.gatewayCode`	`result`
Initiate Authentication Complete Enrolled (eligible for eCommerce)	PROCEED	AUTHENTICATION_AVAILABLE	AUTHENTICATION_IN_PROGRESS	SUCCESS
Initiate Authentication Complete Not Enrolled (not eligible for eCommerce)	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_NOT_SUPPORTED	DECLINED	FAILURE
Acquirer Timeout	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	DECLINED	FAILURE
Invalid BIN response from RuPay PaySecure	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_NOT_SUPPORTED	DECLINED	FAILURE
If RuPay PaySecure is not able to process transactions for an unspecified reason.	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	DECLINED	FAILURE

Examples

Initiate Authentication Request

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{RuPayAuthId}
HTTP Method	PUT

{
    "apiOperation": "INITIATE_AUTHENTICATION",
    "order": {
        "currency": "INR"
    },

    "sourceOfFunds": {

        "provided": {

            "card": {

                "number": "6074829900004946"
            }
        }
    }
}

Initiate Authentication Response

{
    "authentication": {
        "version": "RUPAY"
    },
    "merchant": "TESTMERCHANT",
    "order": {
        "authenticationStatus": "AUTHENTICATION_AVAILABLE",
        "creationTime": "2019-06-12T07:42:39.070Z",
        "currency": "INR",
        "id": "802014086",
        "merchantCategoryCode": "5411",
        "status": "AUTHENTICATION_INITIATED",
        "totalAuthorizedAmount": 0,
        "totalCapturedAmount": 0,
        "totalRefundedAmount": 0
    },
    "response": {
        "gatewayCode": "AUTHENTICATION_IN_PROGRESS",
        "gatewayRecommendation": "PROCEED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "number": "607484xxxxxx4936",
                "scheme": "RUPAY"
            }
        },
        "type": "CARD"
    },
    "timeOfRecord": "2019-06-12T07:42:39.070Z",
    "transaction": {
        "amount": 0,
        "authenticationStatus": "AUTHENTICATION_AVAILABLE",
        "currency": "INR",
        "id": "8286737",
        "type": "AUTHENTICATION"
    },
    "version": "72"
}

Step 2: Authenticate Payer

Where the Initiate Authentication response has indicated authentication to be available (authentication.version=RUPAY) for the RuPay card, you can submit the Authenticate Payer request. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.

The Authenticate Payer operation securely exchanges necessary information, including the card number, between your acquiring bank and RuPay PaySecure. PaySecure returns a unique Transaction ID (tran_ID), which may be used in subsequent Authorization or Pay operations.

Use the same API version as the Initiate Authentication request for the Authenticate Payer request.

Authenticate Payer API Reference [REST] [NVP]

Authenticate Payer Request

You must submit this operation by providing the following mandatory fields:

order.id: The same order.id as the Initiate Authentication operation that preceded it.
transaction.id: The same transaction.id as the Initiate Authentication operation that preceded it.
order.amount: The total amount of the order.
order.currency: The currency of the order.
session.id or sourceOfFunds.provided.card or sourceOfFunds.token: Details of the card being used for the payment.
authentication.redirectResponseUrl: The URL to which you want to redirect the payer after completing the payer authentication process.
device.browserDetails.acceptHeaders: The content of the Accept request-header field as sent from the payer's browser. This is used to determine which content types are supported by the browser.

Authenticate Payer Response

The Authenticate Payer returns the following fields:

response.gatewayCode
transaction.authenticationStatus: Provides more details about the authentication status.
authentication.payerInteraction: Indicates if payer interaction was used to complete the authentication process.
result
authentication.redirect.html: Code to create the authentication UI. Write this content into an empty <DIV> element being the last element in the <BODY> of your payment page.
response.gatewayRecommendation

To determine the next step, check the gateway's recommendation provided in the response.gatewayRecommendation field.

`response.gatewayRecommendation`	Next step
PROCEED	You can proceed to complete the authentication process by allowing the payer to respond to the OTP authentication requested by the issuer.
DO_NOT_PROCEED_ABANDON_ORDER	Do not submit the same request again. The payment service provider, scheme or issuer require you to abandon the order.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	Ask the payer for alternative payment details (For example, a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request.

If the gateway recommends you to PROCEED, then paste content of the authentication.redirect.html response field into the page being displayed to the payer.

The following table shows the Initiate Authentication response for the various Rupay authentication scenarios.

State	`response.gatewayRecommendation`	`transaction.authenticationStatus`	`authentication.payerInteraction`	`response.gatewayCode`	`result`
Authenticate Payer Successful Challenge flow initiated.	PROCEED	AUTHENTICATION_PENDING	REQUIRED	PENDING	PENDING
Issuer Authentication Failed due to invalid card details.	DO_NOT_PROCEED_ABANDON_ORDER	AUTHENTICATION_REJECTED	NOT_REQUIRED	DECLINED	FAILURE
Acquirer Timeout	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	NOT_POSSIBLE	DECLINED	FAILURE
Invalid BIN response from NPCI	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	NOT_POSSIBLE	DECLINED	FAILURE
If RuPay PaySecure is not able to process transactions for an unspecified reason.	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	NOT_POSSIBLE	DECLINED	FAILURE
System Error (a technical error at RuPay PaySecure)	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_UNAVAILABLE	NOT_POSSIBLE	DECLINED	FAILURE

OTP Authentication

The gateway redirects the payer’s browser to the issuer's OTP validation UI (using authentication.redirect.html) where the payer will be prompted to enter a valid OTP, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.

order.id
transaction.id
result
response.gatewayRecommendation

You can determine the authentication outcome using the value returned in the response.gatewayRecommendation field.

`response.gatewayRecommendation`	Next step
PROCEED	You can proceed with the payment as authentication is granted. If the authorization for the payment was successful, proceed with capturing the funds, and if applicable, ship the goods.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	Ask the payer for alternative payment details (For example, a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request.

The gateway updates the Authentication Payer response fields after retrieving the results from the OTP authentication.

State	`response.gatewayRecommendation`	`transaction.authenticationStatus`	`authentication.payerInteraction`	`response.gatewayCode`	`result`
Challenge flow is successful.	PROCEED	AUTHENTICATION_SUCCESSFUL	REQUIRED	APPROVED	SUCCESS
Challenge flow unsuccessful, for example, timeout, invalid OTP, etc.	RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS	AUTHENTICATION_FAILED	REQUIRED	DECLINED	FAILURE

Examples

Authenticate Payer Request

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{RuPayAuthId}
HTTP Method	PUT

{
    "apiOperation": "AUTHENTICATE_PAYER",
    "order": {
        "amount": "33.00",
        "currency": "INR"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "number": "6074849900004936",
                "expiry": {
                    "month": "01",
                    "year": "39"
                },
                "securityCode": "111"
            }
        }
    },
    "device": {
        "ipAddress": "103.14.160.193",
        "browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
        "browserDetails": {
            "acceptHeaders": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
        }
    },
    "authentication": {
        "redirectResponseUrl": "<host>/merchantSimulator/jsp/simple/output.jsp"
    }
}

Authenticate Payer Response

{
    "authentication": {
        "method": "DYNAMIC",
        "payerInteraction": "REQUIRED",
        "redirectHtml": "document.getElementById('redirectToNpciForm').submit();",
        "version": "RUPAY"
    },
    "merchant": "TESTMERCHANT",
    "order": {
        "authenticationStatus": "AUTHENTICATION_PENDING",
        "creationTime": "2019-06-12T07:53:52.190Z",
        "currency": "INR",
        "id": "983684879",
        "merchantCategoryCode": "5411",
        "status": "AUTHENTICATION_INITIATED",
        "totalAuthorizedAmount": 0,
        "totalCapturedAmount": 0,
        "totalRefundedAmount": 0
    },
    "response": {
        "gatewayCode": "PENDING",
        "gatewayRecommendation": "PROCEED"
    },
    "result": "PENDING",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "1",
                    "year": "39"
                },
                "number": "607484xxxxxx4936",
                "scheme": "RUPAY"
            }
        },
        "type": "CARD"
    },
    "timeOfRecord": "2019-06-12T07:53:52.190Z",
    "transaction": {
        "acquirer": {
            "merchantId": "TESTMERCHANT"
        },
        "amount": 33,
        "authenticationStatus": "AUTHENTICATION_PENDING",
        "currency": "INR",
        "id": "745991098",
        "type": "AUTHENTICATION"
    },
    "version": "72"
}

Step 3: Use the Authentication Result in a Payment Operation

When the result of the Authenticate Payer operation indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:

order.id: Provide the order.id that you supplied in the Initiate Authentication and Authenticate Payer operations.
authentication.transactionId: Provide the transaction.id that you supplied in the Initiate Authentication and Authenticate Payer operations. You do not need to include any of the fields in the authentication parameter group, as the gateway will use the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway will pass the required information to the acquirer.

Authentication Transaction ID API Reference [REST] [NVP]

Examples

Pay Request

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method	PUT

{
      "apiOperation":"PAY",
      "order":{
         "amount":"100",
         "currency":"INR"
     },
     "sourceOfFunds":{
         "provided":{
            "card":{
               "expiry":{
                  "month":"01",
                  "year":"39"
               },
               "number":"6074819900004939",
               "securityCode":"111"
            }
         },
         "type":"CARD"
      },
         "authentication": {
           "transactionId":"8286737"
       }
   }

Pay Response

	{
        "authentication": {
            "transactionId": "471707320"
        },
        "authorizationResponse": {
            "transactionIdentifier": "500000000000000000000002347854"
        },
        "gatewayEntryPoint": "WEB_SERVICES_API",
        "merchant": "TESTMERCHANT",
        "order": {
            "amount": 100.00,
            "chargeback": {
                "amount": 0,
                "currency": "INR"
            },
            "creationTime": "2019-07-03T09:08:28.309Z",
            "currency": "INR",
            "id": "802014086",
            "merchantCategoryCode": "4511",
            "status": "CAPTURED",
            "totalAuthorizedAmount": 100.00,
            "totalCapturedAmount": 100.00,
            "totalRefundedAmount": 0.00
        },
        "response": {
            "acquirerCode": "00",
            "acquirerMessage": "Success",
            "gatewayCode": "APPROVED"
        },
        "result": "SUCCESS",
        "sourceOfFunds": {
            "provided": {
                "card": {
                    "brand": "RUPAY",
                    "expiry": {
                        "month": "1",
                        "year": "39"
                    },
                    "fundingMethod": "DEBIT",
                    "issuer": "DMBB9990001",
                    "number": "607481xxxxxx4939",
                    "scheme": "RUPAY",
                    "storedOnFile": "NOT_STORED",
                    "tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"SMS\"}"
                }
            },
            "type": "CARD"
        },
        "timeOfRecord": "2019-07-03T09:08:28.309Z",
        "transaction": {
            "acquirer": {
                "id": "<acquirer_id>",
                "merchantId": "423555234334123"
            },
            "amount": 100.00,
            "authorizationCode": "143835",
            "currency": "INR",
            "frequency": "SINGLE",
            "id": "108379916",
            "receipt": "918409000035",
            "source": "INTERNET",
            "terminal": "88011019",
            "type": "PAYMENT"
        },
        "version": "72"
    }