# RuPay Authentication Implementation using Authentication API
source: https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/rupay-payer-auth/rupay-auth-auth-api/index.md

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 {#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 {#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 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 {#rupay-payer-authentication-through-redirection-mode}

The following diagram illustrates the payment authentication flow, where a payer is authenticated using RuPay.
![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/ruPayRedirect.png)
Warning: 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 {#how-the-redirection-authentication-flow-works-for-a-successful-rupay-authentication}

These are the authentication flows for a successful RuPay authentication.

1. A payer  

   **a.** Browses your shop site.  

   **b.** Selects one or more products.  

   **c.** Proceeds to the payment page.  

   **d.** Selects to pay with a RuPay card that supports RuPay.

2. You initiate authentication with the gateway.

3. Gateway  

   **a.** Checks with RuPay if the card is eligible for RuPay payer authentication.  

   **b.** Returns the authentication details in the response, if RuPay payer authentication is available.

4. You initiate payer authentication.

5. Gateway  

   **a.** Invokes payer authentication when a payer selects the Pay Now or Submit button on the checkout page.  

   **b.** Returns the redirect URL and the RuPay authentication Transaction ID from RuPay in the Authenticate Payer response.

6. You redirect the payer's web browser to the issuer where the payer validates their OTP.

7. The issuer returns the authentication result to the gateway.

8. The gateway redirects the payer directly to your website.

9. You  

   **a.** Use the RuPay Authentication Transaction ID in the Payment operation.  

   **b.** Submit the payment for processing.  

   **c.** Display the order confirmation page to the payer.

## Integrate to use RuPay payer authentication through redirection {#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 {#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.
**Initiate Authentication API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#authentication)

### Initiate authentication request {#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 {#initiate-authentication-response}

If RuPay payer authentication is available, the gateway returns the following fields with **authentication.version**=RUPAY:

* `response.gatewayCode`
* `transaction.authenticationStatus` provides more details about the authentication status.
* `result`
* `response.gatewayRecommendation` determines the next step. Check the gateway recommendation that is provided in the `response.gatewayRecommendation` field and authentication status='Authentication_Available'.

#### Initiate authentication API request and response {#initiate-authentication-api-request-and-response}

**URL:** https://{{host}}/api/rest/version/{{number}}/merchant/{MID}/order/{OID}/transaction/{TID}

```json
{
  "apiOperation": "INITIATE_AUTHENTICATION",
  "order": {
    "currency": "INR"
  },
  "authentication": {
    "purpose": "PAYMENT_TRANSACTION",
    "channel": "PAYER_BROWSER"
  },
  "sourceOfFunds": {
    "provided": {
      "card": {
        "SCHEME_TOKEN": ""
      }
    },
    "type": "SCHEME_TOKEN"
  }
}
```

```json
{
  "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": "100"
}
```

## Step 2: Authenticate payer {#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.
Warning: Use the same API version as the Initiate Authentication request for the Authenticate Payer request. **Authenticate Payer API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#authentication)

### Authenticate payer request {#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 supports.
* `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 {#authenticate-payer-response}

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` 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.gatewayRecommendation`
* `Authenication.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 API request {#authenticate-payer-api-request}

**URL:** https://{{host}}/api/rest/version/{{number}}/merchant/{MID}/order/{OID}/transaction/{TID}

```json
{
  "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 website.

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`

Warning: The gateway updates the Authentication Payer response fields after retrieving the results from the payer authentication. You can see the appropriate result in the 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 API response {#authenticate-payer-api-response}

```json
{
  "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='{{host}}/api/browserPaymentSimulator/npci'> <input type='hidden' name='AccuCardholderId' value='nDczPMjdAO5fA4qYhN3cmBN1710745316111'/> <input type='hidden' name='AccuGuid' value='H2IKBwrvm6zQgA25Um5JU9z1710745316111'/> <input type='hidden' name='AccuReturnURL' value='{{host}}/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": "100"
}
```

## Step 3: Retrieve transaction {#step-3-retrieve-transaction}

When you retrieve a transaction, it provides the authentication status and authentication ID. Once the payer is successfully authenticated, you should trigger the retrieve transaction again to get the latest authentication status. If the status code is 00, the description is "Request was Successful," and the authentication status is "AUTHENTICATION_SUCCESSFUL," then the authentication is confirmed. At this point, you can move forward with authorizing or completing the payment transaction.

#### Retrieve transaction request {#retrieve-transaction-request}

| HTTP Method |                                          URL                                          |
|-------------|---------------------------------------------------------------------------------------|
| GET         | https://{{host}}/api/rest/version/100/merchant/{MID}/order/{OID}/transaction/{TID}'\\ |

#### Retrieve transaction response {#retrieve-transaction-response}

```json
{
  "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": "100"
}
```

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 the 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 {#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.transactionId` for the authentication results that the gateway stored while performing authentication. Gateway passes the required information to the acquirer.

**Authentication Transaction ID API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction)

#### Authorize payer request {#authorize-payer-request}

**URL:** https://{{host}}/api/rest/version/100/merchant/{MID}/order/{OID}/transaction/{TID}'

```json
{
  "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"
  }
}
```

```json
{
  "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": "100"
}
```

## RuPay payer authentication through seamless server to server {#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.
![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/ruPaySeamless.png)
Warning: 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 {#how-the-authentication-flow-works-for-a-successful-rupay-authentication}

These are the authentication flows for a successful RuPay authentication.

1. A payer  

   **a.** Browses your shop site.  

   **b.** Selects one or more products.  

   **c.** Proceeds to the payment page.  

   **d.** Selects to pay with a RuPay card that supports RuPay.  

2. You initiate authentication with the gateway.

3. Gateway  

   **a.** Checks with RuPay if the card is eligible for RuPay payer authentication.  

   **b.** Returns the authentication details in the response, if RuPay payer authentication is available.  

4. You initiate payer authentication.

5. Gateway  

   **a.** Invokes payer authentication when a payer selects the Pay Now or Submit button on the checkout page.  

   **b.** Returns the redirect URL and the RuPay authentication Transaction ID from RuPay in the Authenticate Payer response.  

6. You redirect the payer's web browser to the issuer where the payer validates their OTP.

7. The issuer returns the authentication result to the gateway.

8. The gateway redirects the payer directly to your website.

9. You  

   **a.** Capture the payer's authentication OTP either on your website or on the gateway-hosted password collection page, where the payer completes authentication.  

   **b.** Submit the OTP to the gateway.  

10. The issuer returns the authentication result to the gateway.

11. The gateway redirects the payer directly to your website after the authentication is complete.

12. You  

    **a.** Use the RuPay Authentication Transaction ID in Authorize or Pay.  

    **b.** Display the order confirmation page to the payer.  

## Integrate to use RuPay payer authentication for seamless server to server {#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 {#step-1-initiate-authentication-1}

The Initiate Authentication process checks if RuPay payer authentication is available for a specific card. If the card is a RuPay card, the system verifies whether its BIN qualifies for e-commerce transactions. This check is performed through the Initiate Authentication API.

#### Initiate authentication {#initiate-authentication}

| HTTP Method |                                      URL                                      |
|-------------|-------------------------------------------------------------------------------|
| PUT         | {{host}}/api/rest/version/100/merchant/{MID}/order/{OID}/transaction/{TID}'\\ |

```json
{
  "apiOperation": "INITIATE_AUTHENTICATION",
  "authentication": {
    "purpose": "PAYMENT_TRANSACTION",
    "channel": "PAYER_BROWSER"
  },
  "order": {
    "currency": "INR"
  },
  "sourceOfFunds": {
    "provided": {
      "card": {
        "number": "SCHEME_TOKEN"
      }
    },
    "type": "SCHEME_TOKEN"
  }
}
```

```json
{
  "apiOperation": "INITIATE_AUTHENTICATION",
  "authentication": {
    "purpose": "ADD_CARD",
    "channel": "PAYER_BROWSER"
  },
  "order": {
    "currency": "INR"
  },
  "sourceOfFunds": {
    "type": "SCHEME_TOKEN",
    "provided": {
      "card": {
        "number": "6071489876543212"
      }
    }
  }
}
```

```json
{
  "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": "100"
}
```

## Step 2: Authenticate payer {#step-2-authenticate-payer-1}

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.
Warning: Use the same API version as the Initiate Authentication request for the Authenticate Payer request.

### Authenticate Payer Request {#authenticate-payer-request-1}

Submit the 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.id` provided in the INITIATE_AUTHENTICATION request.
* `transaction.id` indicates that the value must match the `transaction.id` provided 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.currency` provided in the INITIATE_AUTHENTICATION request.
* Token details: Indicates the token and cryptogram in the 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 {#authenticate-payer-response-1}

You receive the API AUTHENTICATE_PAYER response with:

* `response.gatewayRecommendation` in 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 {#authenticate-payer-request-2}

| HTTP Method |                                     URL                                      |
|-------------|------------------------------------------------------------------------------|
| PUT         | {{host}}/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\\ |

```json
{
  "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"
  }
}
```

```json
{
  "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='{{host}}/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": "100"
}
```

This table describes the following fields that authenticate payer returns.

|                Field                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `transaction.authenticationStatus`  | Provides details about the authentication status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `authentication.payerInteraction`   | Indicates if the 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: * Add the text content to a DIV element. Constructs and posts the form automatically and the payer gets redirected to the issuer. Do the following for seamless flow: * Add the text content to a DIV element that displays as a modal window. The OTP entry page displays to the payer. 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 {#step-3-retrieve-transaction-1}

The Retrieve Transaction feature provides essential authentication details and helps determine the next steps for processing a payment.

* The Retrieve Transaction API returns the payer authentication result.
* The transaction response guides your next action.
* You can retrieve details of a completed authentication process.
* If the transaction result includes authentication.status code = 00, authentication.status description = "Request was Successful," and authenticationStatus = "AUTHENTICATION_SUCCESSFUL," then authentication is confirmed.

To proceed with authorization or payment, use these details from the Retrieve Transaction response:

* `order.id` - Use the same order ID from the Initiate Authentication and Authenticate Payer operations.
* `authentication.transactionId` - Use the same transaction ID from the Initiate Authentication and Authenticate Payer operations.

Avoid adding fields in the authentication parameter group. The gateway uses authentication.transactionId to retrieve stored authentication results and passes them to the acquirer.

If you are using the Authentication API, you can view authentication details in the Merchant Administrator portal once the payer authentication is complete.

If authentication is not yet completed (For example, due to a challenge flow), there may be a delay in transaction status when searching for an order or transaction in the Merchant Administrator portal. During this time, you can check the current authentication status using the Retrieve Order or Retrieve Transaction operation.

#### Retrieve order and transaction request {#retrieve-order-and-transaction-request}

| HTTP Method |                                          URL                                          |
|-------------|---------------------------------------------------------------------------------------|
| PUT         | https://{{host}}/api/rest/version/100/merchant/{MID}/order/{OID}/transaction/{TID}'\\ |

#### Retrieve order and transaction response {#retrieve-order-and-transaction-response}

```json
{
  "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": "100"
}
```

### Payer authentication OTP for seamless server to server flow {#payer-authentication-otp-for-seamless-server-to-server-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.

1. Collect an OTP from the customer.
2. 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. 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                  | N/A                            | N/A                                   | PENDING    |
| Re-send OTP limit exhausted    | DO_NOT_PROCEED                     | AUTHENTICATION_REJECTED              | DECLINED                 | N/A                            | N/A                                   | 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    |


Warning: When you design your password collection page to complete payer authentication with your website, use the following element and the attribute.

<br />

3. After you collect the OTP from the customer, OTP is submitted to the gateway using the URL present in action tag in the `authenticate.redirectHTML` in response to authenticate payer operation.

## Handling OTP generation and submission scenarios {#handling-otp-generation-and-submission-scenarios}

A payer can submit an incorrect OTP and regenerate the OTP for up to four times. This is subject to the NPCI guidelines, post that the transaction must be abandoned. These are the possible scenarios:

### Case 1: Resending OTP {#case-1-resending-otp}

1. 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.

2. Payers must select the Resend OTP option on the HTML page, as shown in the following screen.
   ![Resend OTP](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/seamlessFlowSimulator.png)

3. 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 {#retrieve-transaction-request-1}

**URL:** https://{{host}}/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}

#### Retrieve transaction response {#retrieve-transaction-response-1}

```json
{
  "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": "100"
}
```

### Case 2: Reaching maximum OTP request limit {#case-2-reaching-maximum-otp-request-limit}

1. When a payer has reached the maximum number of attempts to request the OTP, the transaction must be abandoned. A `Response.gatewayCode` with a Declined status indicates that the authentication is unsuccessful, so you must abandon the order for your payer.

#### Retrieve transaction request {#retrieve-transaction-request-2}

**URL:** https://{{host}}/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}

#### Retrieve transaction response {#retrieve-transaction-response-2}

```json
{
  "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": "100"
}
```

### Case 3: Entering incorrect OTP for the first time {#case-3-entering-incorrect-otp-for-the-first-time}

1. This is the first attempt when a user enters an incorrect OTP.  
   When the `Response.gatewayCode` has a status of Pending and the gateway recommendation is Do Not Proceed, this indicates that authentication is in progress. So, you should let the payer try entering the OTP again.  
   A payer can try entering OTP until it reaches the maximum number of attempts.

```json
{
  "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": "100"
}
```

### Case 4: Analyzing the OTP verification limit {#case-4-analyzing-the-otp-verification-limit}

1. When a payer has reached the maximum number of attempts to verify the OTP, then the transaction must be abandoned. If the `Response.gatewayCode` has the status of Declined and the gateway recommendation is Do Not Proceed, this indicates that the authentication is unsuccessful. So, you should cancel the order for the payer.

```json
{
  "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": "100"
}
```

## Authorize {#authorize}

After the successful authentication, you can perform either an Authorize or a Pay transaction.

### Authorize request {#authorize-request}

| HTTP Method |                                     URL                                      |
|-------------|------------------------------------------------------------------------------|
| PUT         | {{host}}/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}'\\ |

```json
{
  "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)"
  }
}
```

```json
{
  "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": "100"
}
```

## FAQs for RuPay authentication {#faqs-for-rupay-authentication}

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 an 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 the issuer. Transaction was successfully authorized by the Issuing bank, or the Request was successful. |
| 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, PREVIOUSLY AUTHORIZED, or 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                                                                                                                                                 |
| 410                            | Invalid BIN                                                                                                                                                                 |
| 412                            | Issuer Authentication Failure                                                                                                                                               |
| 450                            | Invalid OTP                                                                                                                                                                 |
| 451                            | Expired OTP                                                                                                                                                                 |
| 452                            | Exhausted OTP verification                                                                                                                                                  |
| 453                            | Exhausted OTP resend count                                                                                                                                                  |
| 454                            | Duplicate requestID                                                                                                                                                         |
| 505                            | SI not registered                                                                                                                                                           |
| 605                            | Invalid token for provided SI registration ID                                                                                                                               |

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](https://developer.mastercard.com/mastercard-gateway/documentation/testing/troubleshooting-faqs/index.md). There is a difference in action attribute of form element in redirect.html in authenticate payer response. For example:

### Redirection response {#redirection-response}

```html
<div id="redirectToNpciAcsSimple" xmlns="http://www.w3.org/1999/html">
  <form id="redirectToNpciForm" method="POST" action="https://{{host}}/api/browserPaymentSimulator/npci">
    <input type="hidden" name="AccuCardholderId" value="nDczPMjdAO5fA4qYhN3cmBN1710745316111" />
    <input type="hidden" name="AccuGuid" value="H2IKBwrvm6zQgA25Um5JU9z1710745316111" />
    <input type="hidden" name="AccuReturnURL" value="https://{{host}}/api/callbackInterface/gateway/08a7bb54ddf9190d7712237071f69c8ebbe3244c1c1c8efdc58f24dd01ecc5a5" />
    <input type="hidden" name="session" value="bee3603032bfb9bbf4b4d36ade6578ca5df28c84058d4a7226ed57b2a26fe0ee" />
    <input type="hidden" name="AccuRequestId" value="NzFhM2RhYzZlMWNkOTFjZTg4YjhmYmMwZDcyZTU2YmM4ZTM5NmJiM2E5ODM3ZTgzMGNiOGQ0Y2YwNDUzNTcyZA==" />
```

### Seamless response {#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://{{host}}/api/callbackInterface/gateway/9993b78a0405ec0471a4b8718ba49b4590bc7c602094269e99cb390387e8e1d9"
  >
    <fieldset id="rupayOTP">
      <div align="left">
        <img class="RupayLogo">
      </div>
    </fieldset>
  </form>
</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.
* 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.
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 the Issuing bank, or the Transaction was successfully validated by BEPG. |
| 01                        | Missing Parameter                                                                                                   |
| 02                        | Invalid Command                                                                                                     |
| 05                        | Do not Honour                                                                                                       |
| 06                        | Transaction Detail not available in the system                                                                      |
| 07                        | Invalid Parameter                                                                                                   |
| 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 PREVIOUSLY AUTHORIZED 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                                                                       |