RuPay
Rupay cards can be authenticated through 2 different methods:
- Redirection Flow – a payment page is redirected to the Issuer’s authentication page to complete the authentication with an OTP (One Time Password)
- Seamless Flow – authentication is performed within your website
Which of above authentication methods can be used depends on the readiness on the issuers’ side. For card BINs supporting both methods a seamless authentication is usually preferred.
Rupay Authentication is initiated with a "PaymentCardPayerAuthTransaction" request containing the following additional mandatory fields:
• termURLrepresenting the URL to which the result of the authentication is redirected.
• cardHolderBrowserParameters containing browserAcceptHeader, browserIP, browserLanguage, browserUserAgent are mandatory
Redirection Flow
In case the issuer supports Redirection flow only, the Gateway returns the parameter acsURL in the response.
You need to perform a redirect as a POST request to the “acsURL” which is generally implemented as auto-submit form. The cardholder shall be redirected to the issuer’s ACS and presented with the UI to collect the authentication details - to enter one-time-password (OTP).
Initiate a payment
In the first step you POST a "PaymentCardPayerAuthTransaction" request type including all mandatory elements.
The following JSON documents represents an examples of a ‘payerauth’ request using the minimum set of elements:
{
"requestType": "PaymentCardPayerAuthTransaction",
"storeId": "{{storeid}}",
"transactionAmount": {
"total": "567",
"currency": "INR"
},
"paymentMethod": {
"paymentCard": {
"number": "{{rupay.cardnumber}}",
"securityCode": "{{rupay.cvv}}",
"expiryDate": {
"month": "{{rupay.exp_mon}}",
"year": "{{rupay.exp_year}}"
}
}
},
"authenticationRequest": {
"authenticationType": "RupayAuthenticationRequest",
"termURL": " https://test3.ipg-online.com/webshop/receiveAndProcess/validate",
"cardHolderBrowserParams": {
"browserAcceptHeaders": "Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8",
"browserIP": "189.6.239.59",
"browserLanguage": "en",
"browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36"
}
}
}
The following JSON document represents an example of a response including the parameteracsURLindicating, that the Redirection Flow is supported by the issuer:
{
"clientRequestId": "2838649",
"apiTraceId": "ZHhj7FzQmYCdKrs_-LWVygAAAWw",
"ipgTransactionId": "84439384258",
"orderId": "R-1230671a-47d4-4630-8534-264b6df75926",
"transactionType": "PAYER_AUTH",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2026"
},
"bin": "607482",
"last4": "4938",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"transactionTime": 1685611500,
"transactionAmount": {
"total": 567.00,
"currency": "INR",
"components": {
"subtotal": 567.00
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting authentication",
"authenticationResponse": {
"params": {
"termURL": " https://test3.ipg-online.com/webshop/receiveAndProcess/validate",
"acsURL": "https://test3.ipg-online.com/connect/gateway/processing?rupayId=84439384258"
}
}
}
The parameter acsURL in the VerificationRedirectResponse represents the URL you need to redirect your consumers to, so that they can perform an authentication.
In the next step you need to POST data to the indicated acsURL usually implemented as an auto-submit form. This needs to be implemented within your website. The cardholder will be redirected to the ACS and presented with the UI to collect the authentication details - enter one-time-password (OTP). After successful authentication the consumer is redirected back the URL you provided within termURL parameter.
NOTE: It is recommended to perform the Extended Hash validation on the fields received in the response and inquiry order status to ensure there were no data tampering in place.
Sales request after successful authentication
In the next step you need to POST a “sale” request and include ipgTransactionId you have received in the first API response from the Gateway.
The following JSON document represents an example of a “sale” transaction using the minimum set of elements:
{
"requestType": "PaymentCardSaleTransaction",
"storeId": "{{storeid}}",
"transactionAmount": {
"total": "567.00",
"currency": "INR"
},
"order": {
"orderId": "R-1230671a-47d4-4630-8534-264b6df75926"
},
"ipgTransactionId": "84439384258"
}
{
"clientRequestId": "2838649",
"apiTraceId": "ZHhkJSmlS9TDNc5bZiHOFQAAA4Y",
"ipgTransactionId": "84439384617",
"orderId": "R-1230671a-47d4-4630-8534-264b6df75926",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2026"
},
"bin": "607482",
"last4": "4938",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"terminalId": "00001113",
"merchantId": "470000000001113",
"transactionTime": 1685611557,
"approvedAmount": {
"total": 567.00,
"currency": "INR",
"components": {}
},
"transactionAmount": {
"total": 567.00,
"currency": "INR",
"components": {}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:145601:4439384617:PPX :315214384258",
"schemeTransactionId": "100112023060100000000000222157",
"processor": {
"referenceNumber": "315214384258",
"authorizationCode": "145601",
"responseCode": "00",
"responseMessage": "success",
"avsResponse": {
"streetMatch": "NO_INPUT_DATA",
"postalCodeMatch": "NO_INPUT_DATA"
}
}
}
Note : In case you are using network tokens to securely store sensitive card information, you must include network token number and token cryptogram in your transaction request with all related mandatory parameters.
Seamless Flow
In case the issuer supports Seamless flow, the Gateway returns the otpVerificationResponse parameter after payerAuth request.
During Seamless flow, the cardholder’s authentication (OTP) is captured within your website and OTP must be submitted to the Gateway in the API request.
Initiate a payment
In the first step you POST a "PaymentCardPayerAuthTransaction" request type including all mandatory elements.
The following JSON document represents an example of a ‘payerauth’ transaction using the minimum set of elements:
{
"requestType": "PaymentCardPayerAuthTransaction",
"storeId": "{{storeid}}",
"transactionAmount": {
"total": "123.50",
"currency": "INR"
},
"paymentMethod": {
"paymentCard": {
"number": "{{rupay.cardnumberSeamless}}",
"securityCode": "{{rupay.cvv}}",
"expiryDate": {
"month": "{{rupay.exp_mon}}",
"year": "{{rupay.exp_year}}"
}
}
},
"authenticationRequest": {
"authenticationType": "RupayAuthenticationRequest",
"termURL": "{{rupay.termUrl}}",
"cardHolderBrowserParams": {
"browserAcceptHeaders": "Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8",
"browserIP": "189.6.239.59",
"browserLanguage": "en",
"browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36"
}
}
}
}
OTP Verification
In case the response includes the parameter otpValidityInMinutes, the Seamless flow has been applied.
With receiving the “otpVerificationResponse”, you must ensure to present a UI to your cardholders to collect the authentication details.
{
"clientRequestId": "2838649",
"apiTraceId": "ZKzVuYerPjAV_eEAG2pbhAAAAvc",
"ipgTransactionId": "84443535451",
"orderId": "R-56a4f23b-0091-4674-8765-72729be08282",
"transactionType": "PAYER_AUTH",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "02",
"year": "2025"
},
"bin": "607148",
"last4": "3212",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"transactionTime": 1689048505,
"transactionAmount": {
"total": 123.50,
"currency": "INR",
"components": {
"subtotal": 123.50
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting authentication",
"authenticationResponse": {
"otpVerificationResponse": {
"otpValidityInMinutes": 1
}
}
}
Once you have captured OTP within your website, you must submit it to the Gateway with PATCH request with “ipgTransactionId” you received in previous response:
{
"authenticationType": "RupayAuthenticationUpdateRequest",
"storeId": "{{storeid}}",
"paymentMethod": {
"paymentCard": {
"number": "{{rupay.cardnumberSeamless}}",
"securityCode": "{{rupay.cvv}}",
"expiryDate": {
"month": "{{rupay.exp_mon}}",
"year": "{{rupay.exp_year}}"
}
}
},
"verifyOtp": "123456"
}
In the response you receive an authentication result:
{
"clientRequestId": "2838649",
"apiTraceId": "ZKzVyevDAHjve3dv5k_DVwAAA8s",
"ipgTransactionId": "84443535451",
"orderId": "R-56a4f23b-0091-4674-8765-72729be08282",
"transactionType": "PAYER_AUTH",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "02",
"year": "2025"
},
"bin": "607148",
"last4": "3212",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"transactionTime": 1689048505,
"approvedAmount": {
"total": 123.5,
"currency": "INR",
"components": {
"subtotal": 123.5
}
},
"transactionAmount": {
"total": 123.5,
"currency": "INR",
"components": {
"subtotal": 123.5
}
},
"transactionStatus": "WAITING",
"approvalCode": "Y:00:OTP verified successfully.",
"authenticationResponse": {
"otpVerificationResponse": {
"responseCode": "00",
"responseDescription": "OTP verified successfully."
}
}
}
OTP Generation
It is possible to also regenerate OTP with submitting the parameter regenerateOtp and PATCH it with ipgTransactionId you have received in the previous step. The Gateway will perform a call to NPCI in the background.
{
"authenticationType": "RupayAuthenticationUpdateRequest",
"storeId": "{{storeid}}",
"paymentMethod": {
"paymentCard": {
"number": "{{rupay.cardnumberSeamless}}",
"securityCode": "{{rupay.cvv}}",
"expiryDate": {
"month": "{{rupay.exp_mon}}",
"year": "{{rupay.exp_year}}"
}
}
},
"regenerateOtp": "true"
}
{
"clientRequestId": "2838649",
"apiTraceId": "ZKzWRSFhD4Fi06xukpEXmgAAAyM",
"ipgTransactionId": "84443535453",
"orderId": "R-7938fc08-ad86-41c6-8147-33fd9a61374a",
"transactionType": "PAYER_AUTH",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "02",
"year": "2025"
},
"bin": "607148",
"last4": "3212",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"transactionTime": 1689048630,
"transactionAmount": {
"total": 123.5,
"currency": "INR",
"components": {
"subtotal": 123.5
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting authentication",
"authenticationResponse": {
"otpVerificationResponse": {
"otpValidityInMinutes": 1
}
}
}
Sale request after successful authentication
It is recommended to perform an inquiry call to ensure the authentication has been successful. In the next step you need to POST a “sale” request and include “ipgTransactionId” you have received in the first API response from the Gateway.
{
"requestType": "PaymentCardSaleTransaction",
"storeId": "{{storeid}}",
"transactionAmount": {
"total": "123.50",
"currency": "INR"
},
"paymentMethod": {
"paymentCard": {
"number": "{{rupay.cardnumberSeamless}}",
"securityCode": "{{rupay.cvv}}",
"expiryDate": {
"month": "{{rupay.exp_mon}}",
"year": "{{rupay.exp_year}}"
}
}
},
"order": {
"orderId": "R-56a4f23b-0091-4674-8765-72729be08282"
},
"ipgTransactionId": "84443535451"
}
In the response you will be provided with the transaction result:
{
"clientRequestId": "2838649",
"apiTraceId": "ZKzV4OvDAHjve3dv5k_DXwAAA7k",
"ipgTransactionId": "84443535452",
"orderId": "R-56a4f23b-0091-4674-8765-72729be08282",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "RUPAY",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "02",
"year": "2025"
},
"bin": "607148",
"last4": "3212",
"brand": "RUPAY"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "RUPAY"
},
"country": "India",
"terminalId": "00001113",
"merchantId": "470000*****1113",
"transactionTime": 1689048544,
"approvedAmount": {
"total": 123.50,
"currency": "INR",
"components": {}
},
"transactionAmount": {
"total": 123.50,
"currency": "INR",
"components": {}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:093906:4443535452:PPX :319209535451",
"schemeTransactionId": "100122023071100000000000230184",
"processor": {
"referenceNumber": "319209535451",
"authorizationCode": "093906",
"responseCode": "00",
"responseMessage": "success",
"avsResponse": {
"streetMatch": "NO_INPUT_DATA",
"postalCodeMatch": "NO_INPUT_DATA"
}
}
}
Updated about 1 year ago
