RuPay Authentication Implementation using Authentication API
This page describes the integration process with Mastercard Gateway to use RuPay authentication which uses the Authentication API.
The gateway supports the RuPay cardholder authentication in the following two ways:
- Redirection payer authentication
- Seamless server to server payer authentication
Redirection payer authentication
An issuer hosts the password entry page where a payer can enter the One Time Password (OTP) for authentication. During a transaction, the issuer sends a password to the cardholder's phone for authentication.
The cardholder can then enter the password into an entry form.
After the verification of a cardholder, the transaction can proceed only if the submitted password matches the given password. On your behalf, the issuer sends a URL for password authentication and hosts the form where a payer can enter the password.
Network traffic can cause a delay in completing the transaction when you do the redirection to the issuer.
Seamless server to server payer authentication
This authentication is triggered and captured either on your payment page or the gateway payment page. The user enters the OTP and completes the card authentication process on your website or application. This streamlines the checkout process.
The following are a few advantages of using the seamless flow:
- Faster transaction process.
- Enhanced experience.
- Improved success rate over OTP on the page of a bank.
RuPay payer authentication through redirection mode
The following diagram illustrates the payment authentication flow, where a payer is authenticated using RuPay.
The following step numbering do not have 1:1 correspondence with the above image. Hence, read them independently.
How the redirection authentication flow works for a successful RuPay authentication
These are the authentication flows for a successful RuPay authentication.
- A payer
- Browses your shop site.
- Selects one or more products.
- Proceeds to the payment page.
- Selects to pay with a RuPay card that supports RuPay.
- You initiate authentication with the gateway.
- Gateway
- Checks with RuPay if the card is eligible for RuPay payer authentication.
- Returns the authentication details in the response, if RuPay payer authentication is available.
- You initiate payer authentication.
- Gateway
- Invokes payer authentication when a payer selects the Pay Now or Submit button on the checkout page.
- Returns the redirect URL and the RuPay authentication Transaction ID from RuPay in the Authenticate Payer response.
- You redirect the payer's web browser to the issuer where, payer validates their OTP.
- The issuer returns the authentication result to the gateway.
- The gateway redirects the payer directly to your website.
- You
- Use the RuPay Authentication Transaction ID in the Payment operation.
- Submit the payment for processing.
- Display the order confirmation page to the payer.
Integrate to use RuPay payer authentication through redirection
This section describes how to integrate to the gateway to use RuPay payer authentication through the redirection mode.
Step 1: Initiate authentication
The Initiate Authentication operation determines if RuPay payer authentication is available to you 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
Provide the following fields to initiate RuPay authentication in the Initiate Authentication request:
- sourceOfFunds.provided.card: Indicates card details used for the payment.
- order.currency: Indicates the currency of the order.
- transaction.id: Indicates a unique identifier for this payment authentication.
- order.id: Indicates a unique identifier for this order.
- aurhentication.purpose: Indicates the purpose of authentication that is, PAYMENT TRANSACTION or ADD CARD.
- authentication.channel: Indicates the channel of authentication, PAYER_BROWSER.
Initiate authentication response
If RuPay payer authentication is available, gateway returns the following fields with authentication.version=RUPAY:
response.gatewayCodetransaction.authenticationStatus: Provides more details about the authentication status.resultresponse.gatewayRecommendation
To determine the next step, check the gateway recommendation that is provided in the response.gatewayRecommendation field and authentication status='Authentication_Available'.
Initiate authentication WS API request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID} |
{
"apiOperation": "INITIATE_AUTHENTICATION",
"order": {
"currency": "INR"
},
"authentication": {
"purpose": "PAYMENT_TRANSACTION",
"channel": "PAYER_BROWSER"
},
"sourceOfFunds": {
"provided": {
"card": {
"SCHEME_TOKEN":
}
},
"type":"SCHEME_TOKEN"
}
}
Initiate authentication WS API response
{
"authentication": {
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"html": "<script id=\"initiate-authentication-script\"></script>"
},
"version": "RUPAY"
},
"merchant": "ATF_39B19221",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2024-03-18T07:01:37.907Z",
"currency": "INR",
"id": "98317278-ab28-4d01-9436-6d270e5bdc84",
"lastUpdatedTime": "2024-03-18T07:01:35.710Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"number": {Scheme_Token},
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-18T07:01:35.710Z",
"timeOfRecord": "2024-03-18T07:01:37.907Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "INR",
"id": "83535990-4953-4d92-8cac-3e8c793d9c2d",
"type": "AUTHENTICATION"
},
"version": "71"
}
Step 2: Authenticate payer
For the Rupay card, wherever the Initiate Authentication response indicates the availability of authentication, authentication.version=RUPAY, you can submit the Authenticate Payer request.
Invoke this when a payer selects the Pay Now or Submit button on the checkout page.
The Authenticate Payer operation securely exchanges necessary information like, the card number or token between your acquiring bank and RuPay. RuPay returns a unique Transaction ID, tran_ID, which can 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
Provide the following mandatory fields to submit this operation:
- order.id: Indicates the same order.id as the Initiate Authentication operation that preceded it.
- transaction.id: Indicates the same transaction.id as the Initiate Authentication operation that preceded it.
- order.amount: Indicates the total amount of the order.
- order.currency: Indicates the currency of the order.
- sourceOfFunds.provided.card: Indicates the details of the scheme token used for the payment.
- authentication.redirectResponseUrl: Indicates the URL to which you want to redirect a payer after completing the payer authentication process.
- device.browserDetails.acceptHeaders: Indicates the content of the Accept request-header field as sent from the payer's browser. This determines which type of content the browser support.
- device.ipAddress: Indicates the IP address of the device that a payer uses in IPv4 nnn.nnn.nnn.nnn format. IPv6 format is not supported.
Authenticate payer response
The Authenticate Payer returns the following fields:
response.gatewayCodetransaction.authenticationStatus: Provides more details about the authentication status.authentication.payerInteraction: Indicates if payer interaction was used to complete the authentication process.resultauthentication.redirect.html: Indicates the code to create the authentication UI. Enter this content into an empty <DIV> element, which must be the last element in the <BODY> of your payment page.response.gatewayRecommendationAuthenication.status.code: Indicates the response as returned from the National Payments Corporation of India (NPCI).Authentication.status.description: Indicates the response as returned from NPCI.
To determine the next step, check the gateways recommendation provided in the response.gatewayRecommendation, authentication.status.code, and description field.
If the gateway recommends PROCEED or authentication.status.code=00/0, then paste the content of the authentication.redirect.html response field into the page that displays to the payer.
Authenticate payer WS API request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID} |
{
"apiOperation": "AUTHENTICATE_PAYER",
"order": {
"amount": "980",
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": {Scheme_Token},
"expiry": {
"month": "05",
"year": "21"
},
"devicePayment": {
"onlinePaymentCryptogram": "APJUR+bB46ysAAKYEAOYGgADFA=="
},
"securityCode": "111"
}
}
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"browserDetails": {
"acceptHeaders": "texct/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
}
},
"authentication": {
"redirectResponseUrl": "www.mastercard.com"
}
}
The gateway redirects the payer’s browser to the issuer's OTP validation UI using authentication.redirect.html, where the payer is prompted to enter a valid OTP. After OTP authentication, the payer is redirected back to your web site.
The following fields are returned in the callback once the payer's browser is returned to your website:
- order.id
- transaction.id
- result
- response.gatewayRecommendation
- authentication.status.code
- authentication.status.description
The gateway updates the Authentication Payer response fields after retrieving the results from the payer authentication. You can see the appropriate result in Retrieve Transaction response API. Do not change the content in authentication.redirect.html that the gateway sends.
To create a redirection request, the following information is extracted from API Response under the Redirect.html:
- Action tag
- AccuCardholderId
- AccuGuid
- AccuReturnURL
- Session
- AccuRequestId
Authenticate payer WS API response
{
"authentication": {
"3ds": {
"transactionId": "001236894402496821710745316111"
},
"amount": 980.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"redirect": {
"html": "<div id='redirectToNpciAcsSimple' xmlns='http://www.w3.org/1999/html'> <form id='redirectToNpciForm' method='POST' action='https://na.gateway.mastercard.com/api/browserPaymentSimulator/npci' > <input type='hidden' name='AccuCardholderId' value='nDczPMjdAO5fA4qYhN3cmBN1710745316111'/> <input type='hidden' name='AccuGuid' value='H2IKBwrvm6zQgA25Um5JU9z1710745316111'/> <input type='hidden' name='AccuReturnURL' value='https://na.gateway.mastercard.com/api/callbackInterface/gateway/08a7bb54ddf9190d7712237071f69c8ebbe3244c1c1c8efdc58f24dd01ecc5a5'/> <input type='hidden' name='session' value='bee3603032bfb9bbf4b4d36ade6578ca5df28c84058d4a7226ed57b2a26fe0ee'/> <input type='hidden' name='AccuRequestId' value='NzFhM2RhYzZlMWNkOTFjZTg4YjhmYmMwZDcyZTU2YmM4ZTM5NmJiM2E5ODM3ZTgzMGNiOGQ0Y2YwNDUzNTcyZA=='/> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectToNpciForm\"); if (e) { e.submit(); e.remove(); } </script> </div>"
},
"status": {
"code": "00",
"description": "Request was successful"
}
"time": "2024-03-18T07:01:55.109Z",
"version": "RUPAY"
},
"merchant": "ATF_39B19221",
"order": {
"amount": 980.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2024-03-18T07:01:56.252Z",
"currency": "INR",
"id": "98317278-ab28-4d01-9436-6d270e5bdc84",
"lastUpdatedTime": "2024-03-18T07:01:53.030Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "21"
},
"number": {Scheme_Token},
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-18T07:01:53.030Z",
"timeOfRecord": "2024-03-18T07:01:56.252Z",
"transaction": {
"acquirer": {
"merchantId": "ATF_39B19221"
},
"amount": 980.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "INR",
"id": "83535990-4953-4d92-8cac-3e8c793d9c2d",
"type": "AUTHENTICATION"
},
"version": "71"
}
Step 3: Retrieve transaction
Retrieve transaction returns the authenticate status and authentication ID in response. After successful authenticate payer, trigger retrieve transaction to get latest authentication status, that is authentication.status code = 00 and authentication.status description ='Request was Successful' and authenticationStatus = 'AUTHENTICATION_SUCCESSFUL'.
This determines successful authentication and then you can proceed with authorize or pay transaction.
Retrieve transaction request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\ |
| HTTP Method | GET |
Retrieve transaction response
{
"authentication": {
"3ds": {
"transactionId": "001236894402496821710745316111"
},
"amount": 980.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"status": {
"code": "ACCU000",
"description": "AUTHENTICATION_SUCCESSFUL"
},
"time": "2024-03-18T07:01:55.109Z",
"version": "RUPAY"
},
"merchant": "ATF_39B19221",
"order": {
"amount": 980.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-18T07:01:53.024Z",
"currency": "INR",
"id": "98317278-ab28-4d01-9436-6d270e5bdc84",
"lastUpdatedTime": "2024-03-18T07:01:56.252Z",
"merchantAmount": 980.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "21"
},
"number": {Scheme_Token},
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-18T07:01:56.252Z",
"timeOfRecord": "2024-03-18T07:01:56.252Z",
"transaction": {
"acquirer": {
"merchantId": "ATF_39B19221"
},
"amount": 980.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "INR",
"id": "83535990-4953-4d92-8cac-3e8c793d9c2d",
"stan": "0",
"type": "AUTHENTICATION"
},
"version": "71"
}
The following codes require your action as received from issuer ACS. Determine the next action based on the response code and description in authentication.status.code and authentication.status.description.
| Response Code | Description | Required Action |
|---|---|---|
| ACCU000 | Authentication Successful | Move to Authorization |
| ACCU100 | Authentication Failed | Decline transaction |
| ACCU200 | Cardholder pressed Cancel button | Decline transaction |
| ACCU400 | Cardholder inactivity timeout | Decline transaction |
| ACCU600 | Invalid data received, posted, or Hash validation failed | Decline transaction |
| ACCU700 | Duplicate Data posted or session already expired | Decline transaction |
| ACCU800 | General Error Encountered | Decline transaction |
Step 4: Use the authentication result in a payment operation
An authentication is successful, when the retrieve transaction operation result indicates that an authentication is successful with the payment authentication.status code = 00 and authentication.status, description is 'Request was Successful', and authenticationStatus is 'AUTHENTICATION_SUCCESSFUL'.
Proceed with authorize or pay transaction and initiate an Authorize or Pay operation. Apart from the standard fields, provide the following fields:
- order.id: Provide the order.id that you entered in the Initiate Authentication and Authenticate Payer operations.
- authentication.transactionId: Provide the
transaction.id that you entered in the Initiate Authentication and Authenticate Payer operations. Do not include any fields in the authentication parameter group.The gateway uses the
authentication.transactionIdfor the authentication results that the gateway stored while performing authentication. Gateway passes the required information to the acquirer.
Authentication Transaction ID API Reference [REST] [NVP]
Authorize payer request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}' |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "600",
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": {Scheme_Token},
"expiry": {
"month": "01",
"year": "21"
},
"devicePayment": {
"onlinePaymentCryptogram": "APJUR+bB46ysAAKYEAOYGgADFA=="
},
"storedOnFile":"TO_BE_STORED"
}
},
"type": "SCHEME_TOKEN"
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)"
},
"authentication": {
"transactionId": "83535990-4953-4d92-8cac-3e8c793d9c2d"
}
}
Authorize payer response
{
"authentication": {
"transactionId": "83535990-4953-4d92-8cac-3e8c793d9c2d"
},
"authorizationResponse": {
"transactionIdentifier": "001236894402496821710745316111"
},
"device": {
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"ipAddress": "103.14.160.193"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "ATF_39B19221",
"order": {
"amount": 600.00,
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-18T07:01:53.024Z",
"currency": "INR",
"id": "98317278-ab28-4d01-9436-6d270e5bdc84",
"lastUpdatedTime": "2024-03-18T07:04:05.555Z",
"merchantAmount": 600.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 600.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Success",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "RUPAY",
"deviceSpecificExpiry": {
"month": "5",
"year": "21"
},
"deviceSpecificNumber": "607484xxxxxx4975",
"expiry": {
"month": "5",
"year": "21"
},
"fundingMethod": "UNKNOWN",
"number": "xxxxxxxxxxxxxxxx",
"scheme": "RUPAY",
"storedOnFile": "TO_BE_STORED",
"tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"DMS\"}"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-18T07:04:05.555Z",
"timeOfRecord": "2024-03-18T07:04:03.187Z",
"transaction": {
"acquirer": {
"id": "NPCI_ACQ_S2S",
"merchantId": "423555234334123"
},
"amount": 600.00,
"authorizationCode": "445510",
"currency": "INR",
"id": "482fd420-ddce-4062-9848-8e44e10e64f7",
"receipt": "407812000002",
"source": "INTERNET",
"stan": "2",
"terminal": "88011019",
"type": "AUTHORIZATION"
},
"version": "71"
}
RuPay payer authentication through seamless server to server
The following diagram illustrates the authentication flow for a payment where a payer is authenticated using RuPay.
The following step numbering do not have 1:1 correspondence with the above image. Hence, read them independently.
How the authentication flow works for a successful RuPay authentication
These are the authentication flows for a successful RuPay authentication.
- A payer
- Browses your shop site.
- Selects one or more products.
- Proceeds to the payment page.
- Selects to pay with a RuPay card that supports RuPay.
- You initiate authentication with the gateway.
- Gateway
- Checks with RuPay if the card is eligible for RuPay payer authentication.
- Returns the authentication details in the response, if RuPay payer authentication is available.
- You initiate payer authentication.
- Gateway
- Invokes payer authentication when a payer selects the Pay Now or Submit button on the checkout page.
- Returns the redirect URL and the RuPay authentication Transaction ID from RuPay 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.
- You
- Capture the payer's authentication OTP either on your website or on the gateway-hosted password collection page, where the payer completes authentication.
- Submit the OTP to the gateway.
- The issuer returns the authentication result to the gateway.
- The gateway redirects the payer directly to your website after the authentication is complete.
- You
- Use the RuPay Authentication Transaction ID in Authorize or Pay.
- Display the order confirmation page to the payer.
Integrate to use RuPay payer authentication for seamless server to server
This section describes how to integrate to the gateway to use RuPay payer authentication through seamless server to server.
Step 1: Initiate authentication
The Initiate Authentication operation determines if RuPay payer authentication is available to you for a given card. If the card type is RuPay, the gateway determines the eligibility of the RuPay card BIN for e-commerce transactions.
- The Initiate Authentication API operation checks the eligibility of RuPay card BIN for eCommerce transactions.
Initiate authentication
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\ |
| HTTP Method | PUT |
'{
"apiOperation": "INITITATE_AUTHENTICATION",
"authentication" :{
"purpose": "PAYMENT_TRANSACTION",
"channel" : "PAYER_BROWSER"
},
"order": {
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "SCHEME_TOKEN"
}
},
"type": "SCHEME_TOKEN"
}
}'
Example request
{
"apiOperation": "INITIATE_AUTHENTICATION",
"order": {
"currency": "INR"
},
"authentication": {
"purpose": "ADD_CARD",
"channel": "PAYER_BROWSER"
},
"sourceOfFunds": {
"type": "SCHEME_TOKEN",
"provided": {
"card": {
"number": "6071489876543212"
}
}
}
}
Initiate authentication response
{
"authentication": {
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"html": "<script id=\"initiate-authentication-script\"></script>"
},
"version": "RUPAY"
},
"merchant": "MERCHANT_A",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2024-03-19T07:12:10.735Z",
"currency": "INR",
"id": "666933919",
"lastUpdatedTime": "2024-03-19T07:12:08.617Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"number": "TOKEN",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-19T07:12:08.617Z",
"timeOfRecord": "2024-03-19T07:12:10.735Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "INR",
"id": "239533306",
"type": "AUTHENTICATION"
},
"version": "71"
}
Step 2: Authenticate payer
For the Rupay card, wherever the Initiate Authentication response indicates the availability of authentication, authentication.version=RUPAY, you can submit the Authenticate Payer request. Invoke this when a payer selects the Pay Now or Submit button on the checkout page.
The Authenticate Payer operation securely exchanges necessary information like, the card number or token between your acquiring bank and RuPay. RuPay returns a unique Transaction context id, tranctx_ID, which can 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 Request
Submit the WS API AUTHENTICATE_PAYER request with the following mandatory fields:
When you integrate directly with the network token service provider, obtain the token details from the provider. Ensure to provide these details to the gateway on an Authenticate payer, Authorization or Pay request to process payments.
- order.id: Indicates that the value must match the
order.idprovided in the INITIATE_AUTHENTICATION request. - transaction.id: Indicates that the value must match the
transaction.idprovided in the INITIATE_AUTHENTICATION request. - order.amount: =0 when Initiate Authentication request has Amount =0.
- order.currency: Indicates that the value must match the
order.currencyprovided in the INITIATE_AUTHENTICATION request. - Token details: Indicates the token and cryptogram in same details as provided in the INITIATE_AUTHENTICATION request.
- authentication.redirectResponseUrl: Indicates the URL to which you redirect payer after they complete the payer authentication process.
- device.browserDetails.acceptHeaders: Provides device information such as ipAddress, browser, browser details, and if required
authentication.channel=PAYER_BROWSER.
Authenticate Payer Response
You receive the WS API AUTHENTICATE_PAYER response with:
response.gatewayRecommendationin one of the following:- DO_NOT_PROCEED
- PROCEED
- result
- response.gatewayCode
- transaction.authenticationStatus
- authentication.payerInteraction
- authentication.redirect.html
- authentication.status.code
- authentication.status.description
Authenticate payer request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\ |
| HTTP Method | PUT |
'{
"apiOperation": "AUTHENTICATE_PAYER",
"order": {
"amount": "8",
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "TOKEN NUMBER",
"expiry": {
"month": "08",
"year": "26"
},
"devicePayment": {
"onlinePaymentCryptogram": "APJUR+bB46ysAAKYEAOYGgADFA=="
},
"securityCode": "123"
}
}
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"browserDetails": {
"acceptHeaders": "texct/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
}
},
"authentication": {
"redirectResponseUrl": "www.mastercard.com"
}
}'
Authenticate payer response
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"redirect": {
"html": "<div id='redirectToNpciAcsSimple' xmlns='http://www.w3.org/1999/html'> <form id='redirectToNpciForm' onsubmit='clickedSubmit(event)' name='redirectToNpciForm' method='POST' target='my_iframe' action='https://na.gateway.mastercard.com/api/callbackInterface/gateway/9993b78a0405ec0471a4b8718ba49b4590bc7c602094269e99cb390387e8e1d9'> <fieldset id='rupayOTP'> <div align ='left'> <img class='RupayLogo' </div>"
},
"status": {
"code": "00",
"description": "Request was successful."
}
"time": "2024-03-19T07:12:17.568Z",
"version": "RUPAY"
},
"merchant": "NPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2024-03-19T07:12:17.668Z",
"currency": "INR",
"id": "666933919",
"lastUpdatedTime": "2024-03-19T07:12:15.474Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "8",
"year": "26"
},
"number": "TOKEN NUMBER",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-19T07:12:15.474Z",
"timeOfRecord": "2024-03-19T07:12:17.668Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_HDFC_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "INR",
"id": "239533306",
"type": "AUTHENTICATION"
},
"version": "71"
}
This table describes the following fields that authenticate payer returns.
| Field | Description | |
|---|---|---|
| transaction.authenticationStatus | Provides details about the authentication status. | |
| authentication.payerInteraction | Indicates if payer interaction completes the authentication process. | |
| authentication.redirect.html | Insert the content of this field into the page that is displayed to the payer. To do this, add the text content to a DIV element. This will construct and post the form automatically and the payer will be redirected to the issuer in case of redirect flow. In the case of a seamless flow, add the text content to a DIV element displayed as a modal window instead. This will then display the OTP entry page to the payer. When you use your own OTP page, submit the OTP to the gateway through the callback URL. | Indicates to add the content of this field into the page that is displayed to the payer.
Do the following for redirect flow:
Do the following for seamless flow:
When you use your own OTP page, submit the OTP to the gateway through the callback URL. |
| response.gatewayRecommendation | Indicates to determine the next step. | |
| response.gatewayCode | Indicates the pending status. | |
| authentication.status.code | Describes the status code that the NPCI BEPG system returns to provide additional information. For example, authentication failed due to invalid or expired OTP. | |
| authentication.status.description | Describes the status that the NPCI BEPG system returns to provide additional information. |
Step 3: Retrieve transaction
Following are the retrieve transaction features:
- Retrieve transaction API returns the payer authenticate result.
- Retrieve transaction response determines your next action.
- Retrieve the details of a transaction. For example, you can retrieve the details of an authentication that you have executed.
- Retrieve Transaction operation result indicates
authentication.status code = 00andauthentication.status.descriptionis 'Request was Successful' and authenticationStatus is 'AUTHENTICATION_SUCCESSFUL'.
Initiate an Authorize or Pay operation with the following details from the Retrieve transaction response:
- order.id: Indicates to provide the order.id that you provided in the Initiate Authentication and Authenticate Payer operations.
- authentication.transactionId: Indicates to provide the transaction.id that you provided in the Initiate Authentication and Authenticate Payer operations.
Do not include any fields in the authentication parameter group, as the gateway uses theauthentication.transactionIdfor the authentication results that it stored while performing authentication. The gateway passes the information to the acquirer.
If you use the Authentication API, you can see the authentication details on the Merchant Administrator portal when the payer authentication is complete.
If the payer authentication is not complete, you may experience a delay in authentication transaction that displays when searching for an order or transaction on the Merchant Administrator portal. For example, going through a challenge flow. In the meantime, you can retrieve the current state of the authentication using the Retrieve Order or Retrieve Transaction operation.
Retrieve order and transaction request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\ |
| HTTP Method | PUT |
Retrieve order and transaction response
{
"authentication": {
"3ds": {
"transactionId": "933358696803544607240738451043"
},
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"status": {
"code": "ACCU000",
"description": "AUTHENTICATION_SUCCESSFUL"
}
"time": "2024-03-19T07:12:17.568Z",
"version": "RUPAY"
},
"device": {
"ipAddress": "103.14.160.193"
},
"merchant": "NPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-19T07:12:15.459Z",
"currency": "INR",
"id": "666933919",
"lastUpdatedTime": "2024-03-19T07:12:38.107Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "8",
"year": "26"
},
"number": "TOKEN NUMBER",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-19T07:12:38.107Z",
"timeOfRecord": "2024-03-19T07:12:38.107Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_HDFC_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "INR",
"id": "239533306",
"stan": "0",
"type": "AUTHENTICATION"
},
"version": "71"
}
Payer authentication OTP for seamless server to server flow
Understanding OTP integration flow
This section explains all the steps that are required to complete authentication to your gateway integration using the Authentication API, including how to use the authentication result to process a payment.
- Collect an OTP from the customer.
- Submit the OTP that the customer submits through the URL that is available in action tag in the
authenticate.redirectHTML, in response to the authenticate payer operation. - After you collect the OTP from the customer, OTP is submitted to the gateway using the URL present in action tag in the
authenticate.redirectHTMLin response to authenticate payer operation.
Once you open HTML in the authentication.redirect.html, you receive the gateway checkout OTP page similar to the following items:
The following table describes the field description of the Authenticate Payer operation.
| State | response.gatewayRecommendation | transaction.authenticationStatus | response.gatewayCode | authentication.status.code | authentication.status.description | Result |
|---|---|---|---|---|---|---|
| Authentication Successful | PROCEED | AUTHENTICATION_PENDING | PENDING | 00/0 | Request was successful. | PENDING |
| Re-send OTP | DO_NOT_PROCEED | AUTHENTICATION_INITIATED | PENDING | NA | NA | PENDING |
| Re-send OTP limit exhausted | DO_NOT_PROCEED | AUTHENTICATION_REJECTED | DECLINED | NA | NA | FAILURE |
| Invalid OTP | DO_NOT_PROCEED | AUTHENTICATION_INITIATED | PENDING | 450 | Invalid OTP | PENDING |
| OTP verification limit exhaust | DO_NOT_PROCEED | AUTHENTICATION_REJECTED | DECLINED | 452 | Exhausted OTP verification | FAILURE |
When you design your password collection page to complete payer authentication with your website, use the following <input> element and the attribute.
<input id='otp' name='otp' type='password' minlength='4' maxlength='10' required='required' title=''>
Handling OTP generation and submission scenarios
A payer can submit an incorrect OTP and regenerate the OTP for up to 4 times. This is subject to the NPCI guidelines, post that the transaction must be abandoned. Following are the various scenarios:
Case 1: Resending OTP
- If your payer is unable to approve the payment because either they have provided an incorrect OTP or after the OTP has expired, they can request another OTP based on the remaining number of retry attempts.
- Payers must select the Resend OTP option on the HTML page, as shown in the following screen.
- Use the Retrieve Transaction operation to retrieve the authentication results after the OTP is submitted.
The Response.gatewayCode with the Pending status indicates that the authentication process is incomplete, and the payer must resubmit the OTP.
Retrieve transaction request
| URL | https://na.gateway.mastercard.com/api/rest/version/77/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
Retrieve transaction response
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"time": "2023-12-06T08:24:30.368Z",
"version": "RUPAY"
},
"merchant": "NPCI_MERCHANT_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2023-12-06T08:24:27.811Z",
"currency": "INR",
"id": "94395092",
"lastUpdatedTime": "2023-12-06T08:25:13.748Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "DO_NOT_PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "28"
},
"number": "607484xxxxxx4936",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2023-12-06T08:25:13.748Z",
"timeOfRecord": "2023-12-06T08:25:13.748Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_MERCHANT_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "INR",
"id": "850037532",
"stan": "0",
"type": "AUTHENTICATION"
},
”version”: “71”
}
Case 2: Reaching maximum OTP request limit
- When a payer has reached the maximum number of attempts to request the OTP, the transaction must be abandoned.
The
Response.gatewayCodewith the Declined status indicates that the authentication is unsuccessful, hence, you must abandon the order for your payer.
Retrieve transaction request
| URL | https://na.gateway.mastercard.com/api/rest/version/77/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
Retrieve transaction response
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"time": "2023-12-07T07:01:58.486Z",
"version": "RUPAY"
},
"merchant": "TESTNPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_REJECTED",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2023-12-07T07:01:56.199Z",
"currency": "INR",
"id": "46800547",
"lastUpdatedTime": "2023-12-07T07:05:56.527Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATION_UNSUCCESSFUL",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "DECLINED",
"gatewayRecommendation": "DO_NOT_PROCEED"
},
"result": "FAILURE",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "28"
},
"number": "607484xxxxxx4936",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2023-12-07T07:05:56.527Z",
"timeOfRecord": "2023-12-07T07:05:56.527Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_MERCHANT_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_REJECTED",
"currency": "INR",
"id": "60002871",
"stan": "0",
"type": "AUTHENTICATION"
},
"version": "71"
}
Case 3: Entering incorrect OTP for the first time
- This is the first attempt when a user enters an incorrect OTP.
TheResponse.gatewayCodewith the status as Pending and the gateway recommendation as Do Not Proceed indicate that authentication is in progress. Hence, you must allow the payer to enter the OTP again.
A payer can try entering OTP until it reaches the maximum number of attempts.
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"time": "2023-12-06T08:24:30.368Z",
"version": "RUPAY"
},
"merchant": "NPCI_MERCHANT_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2023-12-06T08:24:27.811Z",
"currency": "INR",
"id": "94395092",
"lastUpdatedTime": "2023-12-06T08:25:13.748Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "DO_NOT_PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "28"
},
"number": "607484xxxxxx4936",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2023-12-06T08:25:13.748Z",
"timeOfRecord": "2023-12-06T08:25:13.748Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_MERCHANT_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "INR",
"id": "850037532",
"stan": "8",
"type": "AUTHENTICATION"
},
”version”: “71”
}
Case 4: Analyzing the OTP verification limit
- When a payer has reached the maximum number of attempts to verify the OTP, then the transaction must be abandoned.
TheResponse.gatewayCodewith the status as Declined and the gateway recommendation as Do Not Proceed indicate that the authentication is unsuccessful. Hence, you must abandon the order for your payer.
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"time": "2023-12-07T07:01:58.486Z",
"version": "RUPAY"
},
"merchant": "TESTNPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_REJECTED",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2023-12-07T07:01:56.199Z",
"currency": "INR",
"id": "46800547",
"lastUpdatedTime": "2023-12-07T07:05:56.527Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATION_UNSUCCESSFUL",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "DECLINED",
"gatewayRecommendation": "DO_NOT_PROCEED"
},
"result": "FAILURE",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "5",
"year": "28"
},
"number": "607484xxxxxx4936",
"scheme": "RUPAY"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2023-12-07T07:05:56.527Z",
"timeOfRecord": "2023-12-07T07:05:56.527Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_MERCHANT_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_REJECTED",
"currency": "INR",
"id": "60002871",
"stan": "0",
"type": "AUTHENTICATION"
},
"version": "71"
}
Authorize
After the successful authentication, you can perform either an Authorize or a Pay transaction.
Authorize request
| URL | https://na.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\ |
| HTTP Method | PUT |
'{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "8.00",
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "TOKEN NUMBER",
"expiry": {
"month": "08",
"year": "26"
},
"devicePayment": {
"onlinePaymentCryptogram": "APJUR+bB46ysAAKYEAOYGgADFA=="
},
"securityCode": "123"
}
},
"type": "SCHEME_TOKEN"
},
"authentication": {
"transactionId": "239533306"
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)"
}
}'
Authorize response
{
"authentication": {
"transactionId": "239533306"
},
"authorizationResponse": {
"transactionIdentifier": "933358696803544607240738451043"
},
"device": {
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"ipAddress": "103.14.160.193"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "NPCI_A",
"order": {
"amount": 8.00,
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-19T07:12:15.459Z",
"currency": "INR",
"id": "666933919",
"lastUpdatedTime": "2024-03-19T07:13:24.212Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 8.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Success",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "RUPAY",
"deviceSpecificExpiry": {
"month": "8",
"year": "26"
},
"deviceSpecificNumber": "607484xxxxxx4936",
"expiry": {
"month": "8",
"year": "26"
},
"fundingMethod": "UNKNOWN",
"number": "TOKEN NUMBER",
"scheme": "RUPAY",
"storedOnFile": "NOT_STORED",
"tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"DMS\"}"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-19T07:13:24.212Z",
"timeOfRecord": "2024-03-19T07:13:21.802Z",
"transaction": {
"acquirer": {
"id": "NPCI_ACQ _S2S",
"merchantId": "423555234334123"
},
"amount": 8.00,
"authorizationCode": "404163",
"currency": "INR",
"id": "159315708",
"receipt": "407912000003",
"source": "INTERNET",
"stan": "3",
"terminal": "12334448",
"type": "AUTHORIZATION"
},
"version": "71"
}
FAQs for RuPay authentication
What if my RuPay authentication fails?
The NPCI authentication scheme provides additional information in the form of an authentication status code. This specifies the reason for declining the authentication transaction.
When an authentication is declined for invalid BIN, the authentication.status.code and autheication.status.Description indicates the subsequent action.
The following table provides the codes and description that the NPCI has returned.
| authentication.status.code | authentication.status.description |
|---|---|
| 0/00 | Transaction was successfully initiated and card details verified by issuer. Transaction was successfully authorized by Issuing bank, or Request was successful. |
| 01 | Missing Parameter |
| 02 | Invalid Command |
| 13 | Amount Error |
| 96 | System Error, PREVIOUSLY AUTHORIZED, or PREVIOUSLY DECLINED |
| 400 | General Error |
| 401 | Command is Null or Empty |
| 402 | XML is Null or Empty |
| 406 | Not Authenticated |
| 407 | Not Authorized |
| 408 | XML Data Error |
| 410 | Invalid BIN |
| 412 | Issuer Authentication Failure |
| 07 | Invalid Parameter |
| 05 | Do not Honour |
| 41 | DECLINED (lost card) |
| 42 | DECLINED (no account) |
| 43 | DECLINED (stolen) |
| 51 | NON SUFFICIENT FUNDS |
| 54 | EXPIRED CARD |
| 55 | WRONG PIN |
| 57 | DECLINED (cardholder not allowed) |
| 58 | DECLINED (terminal not allowed) |
| 59 | DECLINED (fraud) |
| 61 | DECLINED (exceeds with) |
| 62 | DECLINED (restricted card) |
| 65 | DECLINED (exceeds frequency) |
| 91 | ERROR |
| 92 | NO ROUTING AVAILABLE |
| 93 | Transaction cannot be completed. Compliance violation |
| 96 | PREVIOUSLY DECLINED |
| 110 | NO ACCT |
| 120 | ACCT CLOSED |
| 399 | SYSTEM UNAVAILABLE |
| 409 | Invalid AuthenticationValue |
| 453 | Exhausted OTP resend count |
| 454 | Duplicate requestID |
| 505 | SI not registered |
| 605 | Invalid token for provided SI registration ID |
| 450 | Invalid OTP |
| 451 | Expired OTP |
| 452 | Exhausted OTP verification |
What if my transaction is declined?
NPCI provides additional information in the form of the acquirer code and acquirer message. This specifies the reason for declining the transaction.
For more information, see Troubleshooting and FAQs.
How do I identify the difference between authentication response in Seamless and Redirection?
There is difference in action attribute of form element in redirect.html in authenticate payer response. For example:
Redirection response
"html": "<div id='redirectToNpciAcsSimple' xmlns='http://www.w3.org/1999/html'> <form id='redirectToNpciForm' method='POST' action='https://na.gateway.mastercard.com/api/browserPaymentSimulator/npci' > <input type='hidden' name='AccuCardholderId' value='nDczPMjdAO5fA4qYhN3cmBN1710745316111'/> <input type='hidden' name='AccuGuid' value='H2IKBwrvm6zQgA25Um5JU9z1710745316111'/> <input type='hidden' name='AccuReturnURL' value='https://na.gateway.mastercard.com/api/callbackInterface/gateway/08a7bb54ddf9190d7712237071f69c8ebbe3244c1c1c8efdc58f24dd01ecc5a5'/> <input type='hidden' name='session' value='bee3603032bfb9bbf4b4d36ade6578ca5df28c84058d4a7226ed57b2a26fe0ee'/> <input type='hidden' name='AccuRequestId' value='NzFhM2RhYzZlMWNkOTFjZTg4YjhmYmMwZDcyZTU2YmM4ZTM5NmJiM2E5ODM3ZTgzMGNiOGQ0Y2YwNDUzNTcyZA=='/> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectToNpciForm\"); if (e) { e.submit(); e.remove(); } </script> </div>"
Seamless response
"html": "<div id='redirectToNpciAcsSimple' xmlns='http://www.w3.org/1999/html'> <form id='redirectToNpciForm' onsubmit='clickedSubmit(event)' name='redirectToNpciForm' method='POST' target='my_iframe' action='https://na.gateway.mastercard.com/api/callbackInterface/gateway/9993b78a0405ec0471a4b8718ba49b4590bc7c602094269e99cb390387e8e1d9'> <fieldset id='rupayOTP'> <div align ='left'> <img class='RupayLogo' </div>"
In the redirect authenticate payer response, we receive various parameters like, AccuRequestId, AccuGuid, and so on. We do not receive any parameter in Seamless.
How can I handle Seamless and Redirection OTP page?
- Redirection Flow: A payment page is redirected to the issuer’s authentication page to complete the authentication with an OTP.
- Seamless Flow: An authentication is performed within your website or the gateway hosted password collection page.
What if my RuPay transaction is declined?
NPCI may provide additional information in the form of the acquirer code and acquirer message. This specifies the reason for declining the transaction.
| response.acquirercode | response.acquirermessage |
|---|---|
| 00 | Transaction was successfully authorized by Issuing bank or Transaction was successfully validated by BEPG. |
| 01 | Missing Parameter |
| 02 | Invalid Command |
| 07 | Invalid Parameter |
| 05 | Do not Honour |
| 13 | Amount Error |
| 41 | DECLINED (lost card) |
| 42 | DECLINED (no account) |
| 43 | DECLINED (stolen) |
| 51 | NON SUFFICIENT FUNDS |
| 54 | EXPIRED CARD |
| 55 | WRONG PIN |
| 57 | DECLINED (cardholder not allowed) |
| 58 | DECLINED (terminal not allowed) |
| 59 | DECLINED (fraud) |
| 61 | DECLINED (exceeds with) |
| 62 | DECLINED (restricted card) |
| 65 | DECLINED (exceeds frequency) |
| 91 | ERROR |
| 92 | NO ROUTING AVAILABLE |
| 93 | Transaction cannot be completed. Compliance violation. |
| 96 | SYSTEM ERROR |
| 96 | PREVIOUSLY AUTHORIZED |
| 96 | PREVIOUSLY DECLINED |
| 110 | NO ACCT |
| 120 | ACCT CLOSED |
| 399 | SYSTEM UNAVAILABLE |
| 400 | General Error |
| 401 | Command is Null or Empty |
| 402 | XML is Null or Empty |
| 406 | Not Authenticated |
| 407 | Not Authorized |
| 408 | XML Data Error |
| 409 | Invalid AuthenticationValue |
| 453 | Exhausted OTP resends count |
| 454 | Duplicate requestID |
| 504 | EMI details mismatch |
| 505 | SI not registered |
| 506 | Invalid relationshipID |
| 507 | SFA device token security error |
| 508 | SFA token security error |
| 605 | Invalid token for provided SI registration ID |
| 06 | Transaction Detail not available in the system |