Implementación de la autenticación de RuPay usando la API de RuPay JavaScript

Esta página describe cómo realizar la integración al motor de pagos para usar la autenticación de RuPay utilizando la API de RuPay JavaScript (JS).

Las pautas de integración de RuPay JS complementan las pautas de integración de API de autenticación de RuPay y, como tales, deben utilizarse junto con ellas.

Paso 1: Crear y actualizar una sesión Copied to Clipboard

RuPay JS utiliza la autenticación basada en sesión. Como primer paso, debe crear una sesión, que luego puede actualizar con los campos de solicitud y los valores que desea almacenar en la sesión.

Puede crear una sesión utilizando la llamada Create Session. Es una llamada de API del lado del servidor y es un prerrequisito para la integración con la API de JS. Devuelve los siguientes campos:

  • session.id: un identificador de sesión único que debe proporcionar en solicitudes posteriores para hacer referencia a los contenidos de una sesión.
  • session.authenticationLimit: el límite que proporcionó en la solicitud o el valor predeterminado del motor de pagos.
  • session.aes256Key: la clave que puede usar para descifrar los datos confidenciales que se transmiten al sitio web a través del explorador o dispositivo móvil del pagador.
  • session.version: puede usar este campo para implementar el bloqueo optimista del contenido de la sesión.
  • session.updateStatus: un resumen del resultado del último intento para modificar la sesión.

Referencia de API de Create Session[REST][NVP]

Solicitud de Update Session

Puede agregar o actualizar campos en una sesión utilizando la llamada Update Session. Le permite agregar datos del pago y del pagador en una sesión que posteriormente se puede convertir en la entrada para determinar el riesgo asociado con un pagador en una operación de autenticación. Los siguientes campos son obligatorios en una sesión:

Campos obligatorios

  • sourceOfFunds.provided.card.*: detalles de la tarjeta que se va a utilizar para el pago.
  • order.amount
  • order.currency: la moneda del pedido.
  • transaction.id: identificador único para esta autenticación de pago.
  • order.id: identificador único para este pedido.
  • authentication.channel=PAYER_BROWSER: el canal en el que se inicia la solicitud de autenticación.
  • authentication.purpose=PAYMENT_TRANSACTION: indica el contexto en el que se solicita la autenticación del pagador.
  • authentication.redirectResponseUrl: la URL a la que desea redirigir al pagador después de completar el proceso de autenticación del pagador.

Tenga en cuenta que no se pueden eliminar campos de una sesión, sino solamente sobrescribir valores de los campos existentes.

Referencia de la API de Update Session[REST][NVP]

Paso 2: Inicializar la API Copied to Clipboard

Consulte la API de RuPay JS (rupay.js) en los servidores del motor de pagos. Esto colocará un objeto rupay en la ventana/el espacio de nombres global.

rupay.js Reference[JavaScript]

Cuando haya creado una sesión, inicialice la API utilizando el método configure( ). Se debe llamar a este método durante la carga de la página o cuando DOM se encuentra en estado listo. Debe llamarse solo una vez para la carga de la página. Después de llamar a este método, RuPay JS proporcionará valores de configuración como variables miembro.

Solicitud de inicialización de RuPay JS

Puede inicializar la API de RuPay JS invocando el método configure(), con los siguientes campos obligatorios como argumentos en un objeto de mapa:

  • merchantId: su identificador de negocio en el motor de pagos.
  • sessionId: el ID de sesión que creó utilizando la llamada Create Session.
  • containerId: el ID <div> en su html donde la API inyectará un iframe oculto.
  • callback: una función que se invocará cuando se haya inicializado la API.
  • configuration: valor JSON que admite elementos de datos como userLanguage(optional), versión de la API REST (wsVersion).
Ejemplo de configuración de la API de inicialización

<html>
    <head>
    <script src="https://ap-gateway.mastercard.com/static/rupay/1.0.0/rupay.js"
            data-error="errorCallback"
            data-cancel="cancelCallback">
    </script>

    <script type="text/javascript">
        //The output of this call will return 'false', since the API is not configured yet
        console.log(Rupay.isConfigured());
        /**
        Configure method with the configuration{} parameter set and demonstrates the state change of the rupay object before and after the configure method is invoked.
        */
        Rupay.configure({
    merchantId: "TESTMERCHANT",
    sessionId: "SESSION0002899787259G30902270H6",
    containerId: "ABC",
    callback: function() {
        if (Rupay.isConfigured())
            console.log("Done with configure");
    },
    configuration: {
        userLanguage: "en-US",
        wsVersion: 55
    }
});

    </script>
    </head>
    <body>
        <div id="RupayUI"></div>
    </body>
</html>

Paso 3: Iniciar autenticación Copied to Clipboard

Cuando se hayan obtenido todos los datos del pagador y del pago en una sesión, puede iniciar la autenticación invocando el método initiateAuthentication(). Permite determinar si la autenticación del pagador de RuPay está disponible para el negocio para una determinada tarjeta. Si el tipo de tarjeta es RuPay, el motor de pagos determina la aptitud del BIN de la tarjeta RuPay para transacciones de comercio electrónico.

Solicitud Initiate Authentication

Para iniciar la autenticación, complete los siguientes campos obligatorios en el método initiateAuthentication():

  • orderId: identificador único para este pedido.
  • transactionId: identificador único para esta autenticación de pago.
  • callback: la función de devolución de llamada.
  • optionalParams: (opcional) argumento con cualquier campo adicional de solicitud de API REST de Initiate Authentication, como correlationId.
Respuesta de Initiate Authentication

Si la autenticación de RuPay del pagador está disponible, se devuelven los siguientes campos en el argumento data de la función de devolución de llamada. De lo contrario, la respuesta incluirá un error.

  • data.restApiResponse: contiene la respuesta sin procesar de la llamada de API REST Initiate Authentication.
  • data.correlationId: el último ID de correlación que se usó para realizar la llamada de API REST Initiate Authentication. Permite relacionar la respuesta con la solicitud.
  • data.gatewayRecommendation

Para determinar el siguiente paso, verifique las recomendaciones del motor de pagos que se proporcionan en el campo gatewayRecommendation.

gatewayRecommendation Siguiente paso
PROCEED Puede proceder a autenticar al pagador utilizando la llamada al método authenticatePayer( ).
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicite al pagador detalles de pago alternativos (por ejemplo, una tarjeta nueva u otro método de pago) y vuelva a enviar la solicitud con los nuevos detalles. No vuelva a enviar la misma solicitud.

La tabla siguiente muestra la respuesta de Initiate Authentication para los diversos escenarios de autenticación de Rupay.

Estado response.gatewayRecommendation transaction.authenticationStatus response.gatewayCode result
  • Se completó Initiate Authentication
  • Inscrito (apto para comercio electrónico)
 PROCEED AUTHENTICATION_AVAILABLE AUTHENTICATION_IN_PROGRESS SUCCESS
  • Se completó Initiate Authentication
  • No inscrito (no apto para comercio electrónico)
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_NOT_SUPPORTED DECLINED FAILURE
  • Tiempo de espera excedido del adquirente
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE DECLINED FAILURE
  • Respuesta BIN no válida de RuPay PaySecure
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_NOT_SUPPORTED DECLINED FAILURE
  • Si RuPay PaySecure no puede procesar transacciones por un motivo no especificado.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE DECLINED FAILURE
Ejemplo de solicitud Initiate Authentication

var optionalParams = {
    sourceOfFunds: {
        type: "CARD"
    },
    order: {
        walletProvider: "MASTERPASS_ONLINE"
    }
};

Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) {
    if (data && data.error) {
        var error = data.error;

        //Something bad happened, the error value will match what is returned by the Authentication API
        console.error("error.code : ", error.code);
        console.error("error.msg : ", error.msg);
        console.error("error.result : ", error.result);
        console.error("error.status : ", error.status);
    } else {
        console.log("After Initiate RuPay ", data);

        //data.response will contain information like gatewayRecommendation, authentication version, etc.
        console.log("REST API raw response ", data.restApiResponse);
        console.log("Correlation Id", data.correlationId);
        console.log("Gateway Recommendation", data.gatewayRecommendation);
        console.log("HTML Redirect Code", data.htmlRedirectCode);
        console.log("Authentication Version", data.authenticationVersion);

        switch (data.gatewayRecommendation) {
            case "PROCEED":
                authenticatePayer();//merchant's method
                break;
            case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
                tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method
                break;
        }
    }
}, optionalParams);

Paso 4: Autenticar al pagador Copied to Clipboard

Cuando la respuesta de Initiate Authentication ha indicado que la autenticación debe estar disponible (authentication.version=RUPAY) para la tarjeta RuPay, puede invocar el método authenticatePayer(). Debe invocar esta operación cuando el pagador haga clic en el botón "Pagar ahora" en la página de pago.

La operación Authenticate Payer intercambia de forma segura la información necesaria, incluido el número de tarjeta, entre el banco de su adquirente y RuPay PaySecure. PaySecure devuelve un ID de transacción único (tran_ID), que puede usarse en posteriores operaciones Authorization o Pay.

Solicitud Authenticate Payer

Debe invocar el método authenticatePayer() proporcionando los siguientes campos obligatorios:

  • orderId: el mismo orderId que el método initiateAuthentication() que lo precedió.
  • transactionId: el mismo transactionId que el método initiateAuthentication() que lo precedió.
  • callback: la función de devolución de llamada.
  • optionalParams: (opcional) argumentos con cualquier campo de solicitud adicional de API REST de Authenticate Payer como fullScreenRedirect, billing.
Respuesta de autenticación del pagador

Los siguientes campos se devuelven en el argumento data de la función de devolución de llamada:

  • data.restApiResponse: contiene la respuesta sin procesar de la llamada de API REST Authenticate Payer.
  • data.correlationId: el último ID de correlación que se usó para realizar la llamada de API REST Authenticate Payer. Permite relacionar la respuesta con la solicitud.
  • data.gatewayRecommendation
  • data.htmlRedirectCode: el motor de pagos siempre devuelve este campo para su inserción en la página que se muestra al pagador.

Para determinar el siguiente paso, verifique las recomendaciones del motor de pagos que se proporcionan en el campo gatewayRecommendation devuelto en la devolución de llamada.

gatewayRecommendation Siguiente paso
Continuar Puede proceder a completar el proceso de autenticación (flujo de desafío) o proceder a completar el pago (flujo fluido).
DO_NOT_PROCEED_ABANDON_ORDER No vuelva a enviar la misma solicitud. El proveedor de servicios de pago, el esquema o el emisor le solicitan que abandone el pedido.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicite al pagador detalles de pago alternativos (por ejemplo, una tarjeta nueva u otro método de pago) y vuelva a enviar la solicitud con los nuevos detalles. No vuelva a enviar la misma solicitud.

Si el motor de pagos le recomienda continuar (PROCEED), pegue el contenido del campo de respuesta htmlRedirectCode en la página que se muestra al pagador.

La tabla siguiente muestra la respuesta de authenticatePayer() para los diversos escenarios de autenticación de Rupay.

Estado response.gatewayRecommendation transaction.authenticationStatus authentication.payerInteraction response.gatewayCode result
  • Operación Authenticate Payer correcta
  • Se inició el flujo de desafío.
 PROCEED AUTHENTICATION_PENDING REQUIRED PENDING PENDING
  • La autenticación del emisor falló debido a detalles no válidos de la tarjeta.
 DO_NOT_PROCEED_ABANDON_ORDER AUTHENTICATION_REJECTED NOT_REQUIRED DECLINED FAILURE
  • Tiempo de espera excedido del adquirente
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Respuesta BIN no válida de NPCI
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Si RuPay PaySecure no puede procesar transacciones por un motivo no especificado.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Error del sistema (un error técnico en RuPay PaySecure)
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE

Autenticación OTP

El motor de pagos redirige el explorador del pagador a la IU de validación con OTP del emisor, donde se solicitará al pagador que ingrese una OTP válida, después de lo cual se le redirigirá a su sitio web. Los siguientes campos se devuelven en la devolución de llamada cuando el explorador del pagador se ha devuelto a su sitio web.

  • order.id
  • transaction.id
  • result
  • response.gatewayRecommendation

Puede determinar el resultado de la autenticación utilizando el valor devuelto en el campo response.gatewayRecommendation.

response.gatewayRecommendation Siguiente paso
PROCEED Puede proceder al pago porque la autenticación fue correcta. Si la autorización para el pago fue correcta, continúe con la captura de los fondos y, si procede, envíe la mercancía.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicite al pagador detalles de pago alternativos (por ejemplo, una tarjeta nueva u otro método de pago) y vuelva a enviar la solicitud con los nuevos detalles. No vuelva a enviar la misma solicitud.

El motor de pagos actualiza los campos de respuesta de autenticación del pagador después de recuperar los resultados de la autenticación con OTP.

Estado response.gatewayRecommendation transaction.authenticationStatus authentication.payerInteraction response.gatewayCode result
  • El flujo de desafío fue correcto.
 PROCEED AUTHENTICATION_SUCCESSFUL REQUIRED APPROVED SUCCESS
  • El flujo de desafío no fue correcto, por ejemplo, se excedió el tiempo de espera, la OTP no es válida, etc.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_FAILED REQUIRED DECLINED FAILURE
Ejemplo de solicitud Authenticate Payer
var optionalParams = {
    fullScreenRedirect: true,
    billing: {
        address: {
            city: "London",
            country: "GBR"
        }
    }
};

Rupay.authenticatePayer("5678", "ABC", function (data) {
    if (!data.error) {
        //data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
        console.log("REST API response ", data.restApiResponse);
        console.log("HTML redirect code ", data.htmlRedirectCode);
    }
}, optionalParams);

Paso 5: Usar el resultado de la autenticación en una operación de pago Copied to Clipboard

Cuando el resultado del método authenticatePayer() indica que se puede proceder con el pago (gatewayRecommendation=PROCEED), puede iniciar una operación Authorize o Pay. Además de los campos estándar, debe proporcionar los siguientes campos:

  • order.id: proporcione el orderId que facilitó en los métodos initiateAuthentication() y authenticatePayer().
  • authentication.transactionId: proporcione el transactionId que facilitó en los métodos initiateAuthentication() y authenticatePayer(). No es necesario incluir ninguno de los campos en el grupo de parámetros de autenticación, dado que el motor de pagos utilizará el authentication.transactionId para buscar los resultados de autenticación que almacenó cuando se le pidió que realizara la autenticación. El motor de pagos pasará la información requerida al adquirente.
Solicitud Pay de ejemplo
URL https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Método HTTP PUT 

{
      "apiOperation":"PAY",
      "order":{
         "amount":"100",
         "currency":"INR"
     },
     "sourceOfFunds":{
         "provided":{
            "card":{
               "expiry":{
                  "month":"01",
                  "year":"21"
               },
               "number":"6074819900004939",
               "securityCode":"111"
            }
         },
         "type":"CARD"
      },
         "authentication": {
           "transactionId":"8286737"
       }
   }
Respuesta de ejemplo de Pay

	{
        "authentication": {
            "transactionId": "471707320"
        },
        "authorizationResponse": {
            "transactionIdentifier": "500000000000000000000002347854"
        },
        "gatewayEntryPoint": "WEB_SERVICES_API",
        "merchant": "TESTMERCHANT",
        "order": {
            "amount": 100.00,
            "chargeback": {
                "amount": 0,
                "currency": "INR"
            },
            "creationTime": "2019-07-03T09:08:28.309Z",
            "currency": "INR",
            "id": "802014086",
            "merchantCategoryCode": "4511",
            "status": "CAPTURED",
            "totalAuthorizedAmount": 100.00,
            "totalCapturedAmount": 100.00,
            "totalRefundedAmount": 0.00
        },
        "response": {
            "acquirerCode": "00",
            "acquirerMessage": "Success",
            "gatewayCode": "APPROVED"
        },
        "result": "SUCCESS",
        "sourceOfFunds": {
            "provided": {
                "card": {
                    "brand": "RUPAY",
                    "expiry": {
                        "month": "1",
                        "year": "21"
                    },
                    "fundingMethod": "DEBIT",
                    "issuer": "DMBB9990001",
                    "number": "607481xxxxxx4939",
                    "scheme": "RUPAY",
                    "storedOnFile": "NOT_STORED",
                    "tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"SMS\"}"
                }
            },
            "type": "CARD"
        },
        "timeOfRecord": "2019-07-03T09:08:28.309Z",
        "transaction": {
            "acquirer": {
                "id": "<acquirer_id>",
                "merchantId": "423555234334123"
            },
            "amount": 100.00,
            "authorizationCode": "143835",
            "currency": "INR",
            "frequency": "SINGLE",
            "id": "108379916",
            "receipt": "918409000035",
            "source": "INTERNET",
            "terminal": "88011019",
            "type": "PAYMENT"
        },
        "version": "72"
    }

Pruebe su integración Copied to Clipboard

Para probar la integración, puede usar su perfil de pruebas del negocio en el entorno de Producción.