Implementing RuPay Authentication Using RuPay JavaScript API
This page describes how to integrate to the gateway to use RuPay authentication using the RuPay JavaScript (JS) API.
Step 1: Create and Update Session
RuPay JS uses session-based authentication. As a first step, you must create a session, which you can then update with the request fields and values you wish to store in the session.
You can create a session using the Create Session call. This is a server-side API call and is a prerequisite for integrating with the JS API. It returns the following fields:
session.id: A unique session identifier which you must provide on subsequent requests to reference session contents.session.authenticationLimit: The limit you supplied in the request or the gateway's default value.session.aes256Key: The key you can use to decrypt sensitive data passed to your website via the payers's browser or mobile device.session.version: You can use this field to implement optimistic locking of the session content.session.updateStatus: A summary of the outcome of the last attempt to modify the session.
Create Session API Reference[REST][NVP]
You can add or update fields in a session using the Update Session call. It allows you to add payment and payer data into a session that can subsequently become the input to determine the risk associated with a payer in an authentication operation. The following fields are required in a session:
Mandatory Fields
- sourceOfFunds.provided.card.*: Details of the card being used for the payment.
order.amount- order.currency: The currency of the order.
- transaction.id: A unique identifier for this payment authentication.
- order.id: A unique identifier for this order.
authentication.channel=PAYER_BROWSER: The channel in which the authentication request is being initiated.authentication.purpose=PAYMENT_TRANSACTION: Indicates the context in which payer authentication is being requested.authentication.redirectResponseUrl: The URL to which you want to redirect the payer after completing the payer authentication process.
Please note that you cannot remove fields from a session but can only overwrite values for existing fields.
Step 2: Initialize the API
Reference the RuPay JS API (rupay.js) from the gateway servers. This will place a rupay object into the window/global namespace.
rupay.js Reference[JavaScript]
Once you have created a session, initialize the API using the configure( ) method. This method should be called during the page load or when the DOM is in ready state. It should be called only once for the page load. After calling this method, RuPay JS will provide configuration values as member variables.
You can initialize the RuPay JS API by invoking the configure() method, with the following mandatory fields as arguments in a map object:
merchantId: Your merchant identifier on the gateway.sessionId: The session Id that you created using the Create Session call.containerId: The <div> id in your html where the API will inject a hidden iframe.callback: A function that will be invoked once the API has been initialized.configuration: JSON value supporting data elements like userLanguage(optional), REST API version (wsVersion).
<html>
<head>
<script src="https://gateway-japa.americanexpress.com/static/rupay/1.0.0/rupay.js"
data-error="errorCallback"
data-cancel="cancelCallback">
</script>
<script type="text/javascript">
//The output of this call will return 'false', since the API is not configured yet
console.log(Rupay.isConfigured());
/**
Configure method with the configuration{} parameter set and demonstrates the state change of the rupay object before and after the configure method is invoked.
*/
Rupay.configure({
merchantId: "TESTMERCHANT",
sessionId: "SESSION0002899787259G30902270H6",
containerId: "ABC",
callback: function() {
if (Rupay.isConfigured())
console.log("Done with configure");
},
configuration: {
userLanguage: "en-US",
wsVersion: 55
}
});
</script>
</head>
<body>
<div id="RupayUI"></div>
</body>
</html>
Step 3: Initiate Authentication
Once all payer and payment data has been gathered into a session, you can initiate the authentication by invoking the initiateAuthentication() method. It allows you 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.
You can initiate authentication by providing the following mandatory fields in the initiateAuthentication() method:
- orderId: The unique identifier for this order.
- transactionId: The unique identifier for this payment authentication.
- callback: The callback function.
- optionalParams: (Optional) argument with any additional Initiate Authentication REST API request fields such as correlationId.
If RuPay authentication of the payer is available, the following fields are returned in the data argument of the callback function. Otherwise, the response will include an error.
data.restApiResponse: Contains raw response from the Initiate Authentication REST API call.data.correlationId: The last correlation Id that was used for making the Initiate Authentication REST API call. It allows you to match the response to the request.data.gatewayRecommendation
To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field.
gatewayRecommendation |
Next step |
|---|---|
| PROCEED | You can proceed to authenticate the payer using the authenticatePayer( ) method call. |
| 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 |
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) {
if (data && data.error) {
var error = data.error;
//Something bad happened, the error value will match what is returned by the Authentication API
console.error("error.code : ", error.code);
console.error("error.msg : ", error.msg);
console.error("error.result : ", error.result);
console.error("error.status : ", error.status);
} else {
console.log("After Initiate RuPay ", data);
//data.response will contain information like gatewayRecommendation, authentication version, etc.
console.log("REST API raw response ", data.restApiResponse);
console.log("Correlation Id", data.correlationId);
console.log("Gateway Recommendation", data.gatewayRecommendation);
console.log("HTML Redirect Code", data.htmlRedirectCode);
console.log("Authentication Version", data.authenticationVersion);
switch (data.gatewayRecommendation) {
case "PROCEED":
authenticatePayer();//merchant's method
break;
case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method
break;
}
}
}, optionalParams);
Step 4: Authenticate Payer
Where the Initiate Authentication response has indicated authentication to be available (authentication.version=RUPAY) for the RuPay card, you can invoke the authenticatePayer() method. 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.
You must invoke the authenticatePayer() method by providing the following mandatory fields:
orderId: The same orderId as theinitiateAuthentication()method that preceded it.transactionId: The same transactionId as theinitiateAuthentication()method that preceded it.callback: The callback function.optionalParams: (Optional) arguments with any additional Authenticate Payer REST API request fields such asfullScreenRedirect,billing.
The following fields are returned in the data argument of the callback function:
data.restApiResponse: Contains raw response from the Authentication Payer REST API call.data.correlationId: The last correlation Id that was used for making the Authentication Payer REST API call. It allows you to match the response to the request.data.gatewayRecommendationdata.htmlRedirectCode: The gateway always returns this field for insertion into the page displayed to the payer.
To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field returned in the callback.
gatewayRecommendation |
Next step |
|---|---|
| Proceed | You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow). |
| 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 htmlRedirectCode response field into the page being displayed to the payer.
The following table shows the authenticatePayer() 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 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 |
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
Rupay.authenticatePayer("5678", "ABC", function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code ", data.htmlRedirectCode);
}
}, optionalParams);
Step 5: Use the Authentication Result in a Payment Operation
When the result of the authenticatePayer() method indicates that you can proceed with the payment (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
orderIdthat you supplied in theinitiateAuthentication()andauthenticatePayer()methods. -
authentication.transactionId: Provide the
transactionIdthat you supplied in theinitiateAuthentication()andauthenticatePayer()methods. 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.
| URL | https://gateway-japa.americanexpress.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":"21"
},
"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": "21"
},
"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"
}
Test your integration
To test your integration you can use your TEST merchant profile in the Production environment.