- Integration Guidelines
- Supported Features (Security)
- RuPay Payer Authentication
- Implementing RuPay Authentication using Authentication API
RuPay Authentication Implementation 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.
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]
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.
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 |
---|---|---|---|---|
|
PROCEED | AUTHENTICATION_AVAILABLE | AUTHENTICATION_IN_PROGRESS | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
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" } } } }
{ "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.
Authenticate Payer API Reference [REST] [NVP]
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.
- device.ipAddress: The IP address of the device used by the payer, in IPv4 nnn.nnn.nnn.nnn format. IPv6 format is not supported.
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 |
---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_PENDING | REQUIRED | PENDING | PENDING |
|
DO_NOT_PROCEED_ABANDON_ORDER | AUTHENTICATION_REJECTED | NOT_REQUIRED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
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 |
---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_SUCCESSFUL | REQUIRED | APPROVED | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_FAILED | REQUIRED | DECLINED | FAILURE |
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" } }
{ "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]
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" } }
{ "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" }