Esta guía describe todos los pasos necesarios para agregar 3DS a la integración del motor de pagos utilizando la API de autenticación, incluido cómo usar el resultado de la autenticación para procesar un pago.
La operación Initiate Authentication se utiliza para determinar las versiones de 3DS disponibles para una tarjeta determinada, lo que se basará en lo siguiente:
La operación también permite realizar cualquier actividad en segundo plano (como una llamada al método ACS) con fines como los de recopilación de datos adicionales del pagador para respaldar una operación posterior de Authenticate Payer.
Para iniciar la autenticación, complete los siguientes campos en la solicitud Initiate Authentication:
Parámetro | Existencia | Descripción |
---|---|---|
session.id o sourceOfFunds.provided.card.* o sourceOfFunds.token |
Obligatorio | Detalles de la tarjeta que se va a utilizar para el pago. Tenga en cuenta que también puede utilizar tokens de red y tokens de pago mediante dispositivo como fuente de fondos en la autenticación del pagador. Para obtener más información, consulte las Preguntas frecuentes. |
order.currency |
Obligatorio | La moneda del pedido. |
transaction.id |
Obligatorio | Identificador único para esta autenticación de pago. |
order.id |
Obligatorio | Identificador único para este pedido. |
authentication.channel |
Obligatorio | El canal en el que se inicia la solicitud de autenticación. Puede especificar una de las siguientes opciones:
|
authentication.purpose |
Opcional | De forma predeterminada, este campo está configurado en "PAYMENT_TRANSACTION" para indicar que se debe realizar la autenticación al procesar un pago con tarjeta. No obstante, puede especificar una finalidad diferente para indicar la autenticación sin pago. Consulte Enviar una solicitud de autenticación sin pago. |
authentication.acceptVersions |
Opcional | Las versiones de 3DS que usted aceptará para este pago. Si no especifica una versión, se aceptarán 3DS1 y 3DS2. El motor de pagos utiliza 3DS2 (si el emisor y la tarjeta lo admiten). Si ninguno de los dos está disponible, la autenticación no continuará. |
order.merchantCategoryCode |
Opcional | Proporcione el código de categoría del negocio si desea anular el valor predeterminado configurado en su vínculo de adquirente. |
Para permitir que se complete cualquier proceso de llamada al método ACS antes de intentar la operación Authenticate Payer, se recomienda que envíe la operación Initiate Authentication lo antes posible en su proceso de pago y que actúe de inmediato en función de la respuesta. Esto suele ocurrir cuando el pagador termina de ingresar su número de tarjeta en la página de pago, por ejemplo, evento "onBlur" del campo de entrada Número de tarjeta, o cuando selecciona una tarjeta de las registradas en su cuenta, si su sitio cuenta con capacidades de tarjeta en archivo. Espere al menos diez segundos para que se complete la llamada al método ACS.
Cuando se envía la solicitud Authenticate Payer antes de que se complete la llamada del método ACS, la solicitud Authenticate Payer continúa, pero la respuesta de Authenticate Payer señala que el indicador de finalización del método está establecido en "falso". Si el ACS del emisor ha completado con éxito la llamada al método para obtener información adicional sobre el explorador del pagador, el indicador de método completo en la respuesta de Authenticate Payer indicará "verdadero".
El motor de pagos devuelve los siguientes campos clave en la respuesta de Initiate Authentication:
authentication.version
: si la autenticación EMV 3DS está disponible para el pagador, se devuelve 3DS2. De lo contrario, se devolverá NONE
.authentication.3ds2.methodSupported
: si 3DS2 está disponible y si el ACS del emisor admite una llamada a método, este campo muestra SUPPORTED. El ACS puede utilizar la llamada al método para recopilar datos adicionales antes de la solicitud de autenticación para aumentar la probabilidad de disponer de una autenticación fluida. La llamada al método se activa en un iframe oculto, por lo que es invisible para el pagador. Tampoco proporciona ninguna devolución de llamada al finalizar.transaction.authenticationStatus
: consulte este campo si desea obtener más detalles sobre el estado de autenticación.response.gatewayRecommendation
: este campo le permite determinar el siguiente paso. Tenga en cuenta que esta recomendación se basa solamente en las reglas de filtrado de transacciones 3DS que usted o su proveedor de servicios de pago configuraron.response.gatewayRecommendation |
Siguiente paso |
---|---|
DO_NOT_PROCEED | No continúe con la autenticación 3DS para esta tarjeta, aunque es posible que desee continuar con el pago sin los datos de 3DS. También, puede ofrecer al pagador la opción de probar otro método de pago. |
PROCEED | Puede proceder a autenticar al pagador utilizando la operación Authenticate Payer. |
authentication.redirect.html
: inserte el contenido de este campo en la página que se muestra al pagador. Para hacerlo, agregue el contenido de texto a un elemento DIV oculto y especifique el identificador de script en HTML DOM. De esta manera se creará y publicará el formulario automáticamente. Por ejemplo:
div.innerHtml= response.authentication.redirect.html; eval(document.getElementById('initiate-authentication-script').text)
URL | https://evopaymentsmexico.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
Método HTTP | PUT |
{ "authentication":{ "acceptVersions":"3DS1,3DS2", "channel":"PAYER_BROWSER", "purpose":"PAYMENT_TRANSACTION" }, "correlationId":"test", "order":{ "currency":"AUD" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>" } } }, "apiOperation":"INITIATE_AUTHENTICATION" }
{ "authentication": { "3ds2": { "directoryServerId": "A999999999", "methodCompleted": false, "methodSupported": "SUPPORTED", "protocolVersion": "2.1.0", "requestorId": "test40Field@S^2sfds2ID", "requestorName": "test40Field@S^2sfds2Name" }, "acceptVersions": "3DS1,3DS2", "channel": "PAYER_BROWSER", "purpose": "PAYMENT_TRANSACTION", "redirect": { "customizedHtml": { "3ds2": { "methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==", "methodUrl": "<method_url>" } }, "html": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"<method_url>" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>" }, "version": "3DS2" }, "correlationId": "test", "merchant": "TEST3DS12AUTH", "order": { "authenticationStatus": "AUTHENTICATION_AVAILABLE", "creationTime": "2022-06-24T06:57:32.714Z", "currency": "USD", "id": "TEST4", "lastUpdatedTime": "2022-06-24T06:57:32.661Z", "merchantCategoryCode": "1234", "status": "AUTHENTICATION_INITIATED", "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalRefundedAmount": 0 }, "response": { "gatewayCode": "AUTHENTICATION_IN_PROGRESS", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "fundingMethod": "CREDIT", "number": "512345xxxxxx0008", "scheme": "MASTERCARD" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-24T06:57:32.661Z", "timeOfRecord": "2022-06-24T06:57:32.714Z", "transaction": { "amount": 0, "authenticationStatus": "AUTHENTICATION_AVAILABLE", "currency": "USD", "id": "1", "type": "AUTHENTICATION" }, "version": "67" }
Cuando la respuesta de Initiate Authentication ha indicado que la autenticación está disponible (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE) y una vez que se hayan reunido todos los datos del pagador y del pago, puede enviar la solicitud Authenticate Payer. Debe invocar esta operación cuando el pagador haga clic en el botón "Pagar ahora" en la página de pago.
Envíe esta operación proporcionando los siguientes campos.
Parámetro | Existencia | Descripción |
---|---|---|
session.id o sourceOfFunds.provided.card.* o sourceOfFunds.token |
Obligatorio | Detalles de la tarjeta que se va a utilizar para el pago. |
order.amount |
Obligatorio | El monto total del pedido. |
transaction.id |
Obligatorio | El mismo transaction.id que la operación Initiate Authentication que lo precedió. |
order.id |
Obligatorio | El mismo order.id que la operación Initiate Authentication que lo precedió. |
sourceOfFunds.provided.card.nameOnCard |
Opcional | Obligatorio si admite las autenticaciones de EMVCo de conmutador local de ITMX. |
sourceOfFunds.provided.card.number |
Opcional | Obligatorio si admite las autenticaciones de EMVCo de conmutador local de ITMX. |
sourceOfFunds.provided.card.expiry |
Opcional | Obligatorio si admite las autenticaciones de EMVCo de conmutador local de ITMX. |
authentication.redirectResponseUrl |
Opcional | La URL a la que desea redirigir al pagador después de completar el proceso de autenticación del pagador. Debe proporcionar esta dirección URL, a menos que esté seguro de que no habrá interacción con el pagador. |
order.merchantCategoryCode |
Opcional | Si no proporciona un valor, se utilizará el valor predeterminado configurado en su perfil del negocio. |
device.browser |
Opcional | Obligatorio si authentication.channel=PAYER_BROWSER. |
device.ipAddress |
Opcional | Obligatorio si authentication.channel=PAYER_BROWSER, pero con la disposición de excluir, cuando sea necesario, para cumplir con la legislación local. Obligatorio si admite las autenticaciones de EMVCo de conmutador local de ITMX. Las autenticaciones EMV 3DS admiten direcciones IPv4 e IPv6 desde la versión 79 de API. IPv6 solo se utiliza en la autenticación EMV 3DS y no se utiliza en ninguna operación posterior de Authorize, Pay u otra operación. |
Grupo de parámetros de device.browserDetails |
Opcional | Obligatorio si authentication.channel=PAYER_BROWSER. |
Grupo de parámetros de billing.address |
Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que esté disponible. |
Grupo de parámetros de shipping.address |
Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que esté disponible. |
Grupo de parámetros de customer |
Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que esté disponible. |
El motor de pagos devuelve los siguientes campos clave en la respuesta de Authenticate Payer:
transaction.authenticationStatus
: consulte este campo si desea obtener más detalles sobre el estado de autenticación.response.gatewayRecommendation
: este campo le permite determinar si debe proceder a una transacción financiera o no. Esta recomendación se basa únicamente en las reglas de filtrado de transacciones 3DS configuradas por usted o por su proveedor de servicios de pago.response.gatewayRecommendation |
Siguiente paso |
---|---|
DO_NOT_PROCEED | No continúe con esta tarjeta, ya que la autenticación se rechazó o no está disponible, aunque es posible que desee continuar con el pago sin los datos de 3DS. También, puede ofrecer al pagador la opción de probar otro método de pago. |
PROCEED | Puede proceder a completar el proceso de autenticación (flujo de desafío) o proceder a completar el pago (flujo fluido). |
authentication.redirect.html
: inserte el contenido de este campo en la página que se muestra al pagador. Para hacerlo, agregue el contenido de texto a un elemento DIV y especifique el identificador de script en HTML DOM. De esta manera se creará y publicará el formulario automáticamente. Por ejemplo:
div.innerHtml= response.authentication.redirect.html; eval(document.getElementById('authenticate-payer-script').text)
Esto redirigirá el explorador del pagador directamente a su sitio web. Puede proceder a enviar un pago posterior al motor de pagos. El motor de pagos obtendrá los datos de autenticación relacionados con el pago y se asegurará de que los pagos solo se procesen cuando hayan pasado todas las reglas de filtrado de transacciones 3DS (configuradas por usted o su proveedor de servicios de pago).
Esto redirigirá el explorador del pagador al ACS donde se presentará la IU de desafío del emisor, después de lo cual el pagador será redirigido al sitio web que usted posee. Los siguientes campos se devuelven en la devolución de llamada cuando el explorador del pagador se ha devuelto a su sitio web.
Puede determinar el resultado de la autenticación utilizando el valor devuelto en el campo response.gatewayRecommendation
. Esta recomendación se basa únicamente en las reglas de filtrado de transacciones 3DS configuradas por usted o por su proveedor de servicios de pago.
Si desea datos de respuesta adicionales, puede utilizar la operación Retrieve Transaction.
response.gatewayRecommendation |
Siguiente paso |
---|---|
DO_NOT_PROCEED | No continúe con esta tarjeta, ya que la autenticación se rechazó o no está disponible, aunque es posible que desee continuar con el pago sin los datos de 3DS. También, puede ofrecer al pagador la opción de probar otro método de pago. |
PROCEED | Puede proceder al pago porque la autenticación fue correcta. |
Los campos devueltos en la respuesta de Authenticate Payer dependen del flujo vigente (fluido frente a desafío), cómo se inició la solicitud de autenticación (authentication.channel) y el mecanismo de autenticación para la solicitud (sesión, certificado o contraseña).
Los siguientes campos se devuelven para una solicitud autenticada de certificado/contraseña. Para una operación autenticada por sesión, la respuesta se filtra para eliminar datos que no están relacionados con el pagador y solo se devuelven los campos de la lista blanca. Para obtener más información, consulte autenticación de sesión.
Response Field |
Autenticado por el negocio |
---|---|
authentication.method | Sí |
authentication.3ds.authenticationToken | * |
authentication.3ds.acsEci | Sí |
authentication.3ds.transactionId | Sí |
authentication.3ds2.transactionStatus | * |
authentication.3ds2.acsTransactionId | * |
authentication.3ds2.dsTransactionId | * |
authentication.3ds2.3dsServerTransactionId | * |
authentication.3ds2.3dsServerTransactionId | * |
authentication.3ds2.protocolVersion | * |
authentication.amount | Sí |
authentication.redirect.html | Sí |
authentication.time | Sí |
response.gatewayRecommendation | Sí |
transaction.type | Sí |
version | Sí |
timeOfRecord | Sí |
result | Sí |
response.debugInformation | * |
URL | https://evopaymentsmexico.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
Método HTTP | PUT |
{ "authentication":{ "redirectResponseUrl":"<host>/merchantSimulator/jsp/simple/output.jsp" }, "correlationId":"test", "device": { "browser": "MOZILLA", "browserDetails": { "3DSecureChallengeWindowSize": "FULL_SCREEN", "acceptHeaders": "application/json", "colorDepth": 24, "javaEnabled": true, "language": "en-US", "screenHeight": 640, "screenWidth": 480, "timeZone": 273 }, "ipAddress": "127.0.0.1" }, "order":{ "amount":"100", "currency":"AUD" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>", "expiry":{ "month":"1", "year":"39" } } } }, "apiOperation": "AUTHENTICATE_PAYER" }
{ "authentication": { "3ds": { "transactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8" }, "3ds2": { "3dsServerTransactionId": "cf976f0d-cb19-454f-a5b3-3cf09ae07e38", "acsTransactionId": "c8027c6a-94da-480d-9270-85098bc680d5", "directoryServerId": "A999999999", "dsTransactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8", "methodSupported": "NOT_SUPPORTED", "protocolVersion": "2.1.0", "requestorId": "test40Field@S^2sfds2ID", "requestorName": "test40Field@S^2sfds2Name", "sdk": { "timeout": 400, "uiType": "TEXT" }, "transactionStatus": "C" }, "amount": 100.00, "method": "OUT_OF_BAND", "payerInteraction": "REQUIRED", "redirect": { "customizedHtml": { "3ds2": { "acsUrl": "<acs_url>", "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9" } }, "domainName": "<acs_domain>", "html": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"<acs_url>" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>" }, "time": "2022-06-24T07:04:34.836Z", "version": "3DS2" }, "correlationId": "test", "device": { "browser": "mozilla", "ipAddress": "127.0.0.1" }, "merchant": "TEST3DS12AUTH", "order": { "amount": 100.00, "authenticationStatus": "AUTHENTICATION_PENDING", "creationTime": "2022-06-24T07:03:43.780Z", "currency": "USD", "id": "TEST6", "lastUpdatedTime": "2022-06-24T07:04:34.795Z", "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": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "CREDIT", "number": "512345xxxxxx8212", "scheme": "MASTERCARD" } }, "type": "CARD" }, "timeOfLastUpdate": "2022-06-24T07:04:34.795Z", "timeOfRecord": "2022-06-24T07:03:43.780Z", "transaction": { "acquirer": { "merchantId": "123456" }, "amount": 100.00, "authenticationStatus": "AUTHENTICATION_PENDING", "currency": "USD", "id": "1", "type": "AUTHENTICATION" }, "version": "67" }
Cuando el resultado de la operación Authenticate Payer indica que se puede proceder con el pago (response.gatewayRecommendation=PROCEED), puede iniciar una operación Authorize o Pay. Además de los campos estándar, debe proporcionar los siguientes campos:
URL | https://evopaymentsmexico.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
Método HTTP | PUT |
{ "apiOperation":"PAY", "authentication":{ "transactionId":"<your_transaction_ID>" }, "order":{ "amount":"100", "currency":"AUD", "reference":"<your_order_ID>" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>", "expiry":{ "month":"1", "year":"39" } } }, "type":"CARD" }, "transaction":{ "reference":"<your_order_ID>" } }
{ "authentication":{ "3ds":{ "acsEci":"02", "authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af" }, "3ds2":{ "dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af", "protocolVersion":"2.1.0", "transactionStatus":"Y" }, "transactionId":"249213216", "version":"3DS2" }, "authorizationResponse":{ "posData":"1605S0100130", "transactionIdentifier":"TidTest" }, "device":{ "browser":"MOZILLA", "ipAddress":"127.0.0.1" }, "gatewayEntryPoint":"WEB_SERVICES_API", "merchant":"TEST_3DS2-1", "order":{ "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "chargeback":{ "amount":0, "currency":"AUD" }, "creationTime":"2021-04-13T02:11:06.102Z", "currency":"AUD", "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "lastUpdatedTime":"2021-04-13T02:11:57.049Z", "merchantAmount":100.00, "merchantCategoryCode":"1234", "merchantCurrency":"AUD", "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "status":"CAPTURED", "totalAuthorizedAmount":100.00, "totalCapturedAmount":100.00, "totalRefundedAmount":0.00 }, "response":{ "acquirerCode":"00", "gatewayCode":"APPROVED" }, "result":"SUCCESS", "sourceOfFunds":{ "provided":{ "card":{ "brand":"MASTERCARD", "expiry":{ "month":"1", "year":"39" }, "fundingMethod":"CREDIT", "issuer":"<issuer>", "number":"512345xxxxxx0008", "scheme":"Mastercard", "storedOnFile":"NOT_STORED" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-13T02:11:57.049Z", "timeOfRecord":"2021-04-13T02:11:56.973Z", "transaction":{ "acquirer":{ "batch":1, "id":"<acquirer_id>", "merchantId":"99554411" }, "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "authorizationCode":"028941", "currency":"AUD", "id":"1", "receipt":"1908266016", "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "source":"INTERNET", "stan":"496", "terminal":"1234", "type":"PAYMENT" }, "version":"60" }
Puede usar la API de autenticación como una API del lado del servidor o del lado del cliente.
Para ver otras preguntas frecuentes generales sobre 3-D Secure, consulte Preguntas frecuentes sobre la autenticación.
Para obtener más información sobre cómo probar su integración, consulte Pruebe su integración.
Derechos de autor © 2023 Mastercard