This page describes how to integrate to the gateway to use RuPay authentication using the Authentication API.
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:
This section describes how to integrate to the gateway to use RuPay Payer 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:
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" }
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:
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 |
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.
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" }
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:
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" }
Copyright © 2023 Mastercard