- Pautas de integración
- Características soportadas (seguridad)
- Autenticación de pagador de RuPay
- Implementación de la autenticación de RuPay usando la API de RuPay JavaScript
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).
Paso 1: Crear y actualizar una sesión
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]
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.
Paso 2: Inicializar la API
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.
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).
<html>
<head>
<script src="https://mtf.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
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.
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.
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 |
|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_AVAILABLE | AUTHENTICATION_IN_PROGRESS | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) {
if (data && data.error) {
var error = data.error;
//Something bad happened, the error value will match what is returned by the Authentication API
console.error("error.code : ", error.code);
console.error("error.msg : ", error.msg);
console.error("error.result : ", error.result);
console.error("error.status : ", error.status);
} else {
console.log("After Initiate RuPay ", data);
//data.response will contain information like gatewayRecommendation, authentication version, etc.
console.log("REST API raw response ", data.restApiResponse);
console.log("Correlation Id", data.correlationId);
console.log("Gateway Recommendation", data.gatewayRecommendation);
console.log("HTML Redirect Code", data.htmlRedirectCode);
console.log("Authentication Version", data.authenticationVersion);
switch (data.gatewayRecommendation) {
case "PROCEED":
authenticatePayer();//merchant's method
break;
case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method
break;
}
}
}, optionalParams);
Paso 4: Autenticar al pagador
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.
Debe invocar el método authenticatePayer() proporcionando los siguientes campos obligatorios:
orderId: el mismo orderId que el métodoinitiateAuthentication()que lo precedió.transactionId: el mismo transactionId que el métodoinitiateAuthentication()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 comofullScreenRedirect,billing.
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.gatewayRecommendationdata.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 |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_PENDING | REQUIRED | PENDING | PENDING |
|
DO_NOT_PROCEED_ABANDON_ORDER | AUTHENTICATION_REJECTED | NOT_REQUIRED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
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 |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_SUCCESSFUL | REQUIRED | APPROVED | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_FAILED | REQUIRED | DECLINED | FAILURE |
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
Rupay.authenticatePayer("5678", "ABC", function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code ", data.htmlRedirectCode);
}
}, optionalParams);
Paso 5: Usar el resultado de la autenticación en una operación de pago
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
orderIdque facilitó en los métodosinitiateAuthentication()yauthenticatePayer(). -
authentication.transactionId: proporcione el
transactionIdque facilitó en los métodosinitiateAuthentication()yauthenticatePayer(). 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.
| URL | https://mtf.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"
}
}
{
"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
Para probar la integración, puede usar su perfil de pruebas del negocio en el entorno de Producción.