- Pautas de integración
- Características soportadas (seguridad)
- Autenticación 3-D Secure
Autenticación 3-D Secure
La autenticación 3-Domain Secure™ (3-D Secure o 3DS) está diseñada para proteger las compras en línea contra el fraude de tarjetas de crédito, al permitirle autenticar al pagador antes de enviar una transacción Authorization o Pay. Lo que hace la autenticación 3DS es redirigir al pagador al emisor de su tarjeta, donde debe ingresar una contraseña previamente registrada.
El Mastercard Gateway admite la autenticación 3DS mediante Mastercard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™ y Diners Club ProtectBuy™.
Prerrequisitos
- Debes estar registrado con tu adquirente para usar 3DS
- Debe estar habilitado para un esquema de 3DS en su perfil del negocio con el Mastercard Gateway.
Experiencia del pagador de 3DS
En esta sección se describe un ejemplo de flujo de pago para el sitio de su tienda, en que el pagador se autentica con 3DS.
El flujo de pago para una autenticación correcta es el siguiente:
- Un pagador navega por el sitio de su tienda, selecciona uno o más productos, accede a la página de pago y selecciona pagar con una tarjeta compatible con 3DS.
- Verificar la inscripción 3DS: usted le pide a Mastercard Gateway que consulte con el esquema de tarjeta si la tarjeta está inscrita para 3DS.
- Autenticar al pagador: después de confirmar que la tarjeta está inscrita, usted redirige el explorador del pagador a la página de autenticación 3DS de su emisor. El pagador ingresa su contraseña 3DS y envía la información. El emisor le devuelve el resultado de la autenticación.
- Procesar resultado de ACS: usted le pide a Mastercard Gateway que procese el resultado de la autenticación. Mastercard Gateway le proporciona a usted los detalles de la respuesta de autenticación recibida del emisor.
- Usar el resultado 3DS en una operación de pago: usted envía el pago para procesamiento.
- La página de confirmación del pedido se le muestra al pagador.
Integración para usar la autenticación 3DS
En esta sección se describe cómo realizar una integración para que el Mastercard Gateway utilice 3DS.
Puede comprobar si una tarjeta está inscrita al proporcionar los campos siguientes en la solicitud Check 3DS Enrollment:
3DSecureId: Su identificador único para esta autenticación. Debe incluir este mismo identificador en todas las operaciones posteriores.3DSecure.authenticationRedirect.responseUrl: La URL a la que desea redirigir al pagador después de completar el proceso de autenticación 3DSorder.amount: El importe total del pedidoorder.currency: la moneda del pedidosourceOfFunds.provided.cardosession.idosourceOfFunds.token: detalles de la tarjeta que se va a utilizar para el pago- (Opcional)
3DSecure.goodsDescription:puede proporcionar una breve descripción de la mercancía que se va a comprar. Si el servidor de control de acceso (ACS) del emisor lo admite, esta descripción se mostrará en la página de autenticación que se presenta al pagador.
Mastercard Gateway proporciona los resultados de la comprobación de inscripción en la respuesta:
3DSecure.xid: un identificador de transacción único generado por el Mastercard Gateway para la autenticación 3DS.3DSecure.summaryStatus: una respuesta resumida que indica el estado general de inscripción de la tarjetaresponse.3DSecure.gatewayCode: una respuesta detallada que describe el estado de inscripción de la tarjeta
Debe observar 3DSecure.summaryStatus para determinar cuál es el siguiente paso. Esto se resume en la siguiente tabla:
| 3DSecure.summaryStatus | Siguiente paso |
|---|---|
| CARD_ENROLLED | La tarjeta está inscrita para 3DS. Proceda a autenticar al pagador. |
| CARD_NOT_ENROLLED | La tarjeta no está inscrita para 3DS. Proceda con la operación de pago, incluyendo el 3DSecureID sobre la solicitud. |
| CARD_DOES_NOT SUPPORT_3DS | La tarjeta no admite 3DS y no se puede proceder con la autenticación de 3DS. |
| AUTHENTICATION_NOT_AVAILABLE | Hubo un error. Proceda con la operación de pago, incluyendo el 3DSecureID sobre la solicitud |
Si la tarjeta está registrada (response.3DSecure.gatewayCode = CARD_ENROLLED), debe redirigir el explorador del pagador al sitio web del emisor de la tarjeta para su autenticación. Simplemente devuelva el contenido proporcionado en el 3DSecure.authenticationRedirect.simple.htmlBodyContent al explorador del pagador.
Cuando finalice el proceso de autenticación en el sitio web del emisor de la tarjeta, el servidor de control de acceso (ACS) del emisor le devuelve la respuesta de autenticación a usted en forma de un mensaje HTTP a la URL de respuesta (3DSecure.authenticationRedirect.responseUrl) que especificó en la solicitud Check 3DS Enrollment.
El mensaje de respuesta de autenticación de pago (PARes) devuelto se proporciona como un valor codificado base64. Para decodificar este valor, transfiera el PARes al campo 3DSecure.paRes en la operación Process ACS Result y envíe la operación. Mastercard Gateway proporciona los resultados de la autenticación en la respuesta:
3DSecure.summaryStatus: una respuesta resumida que indica el estado de autenticación generalresponse.3DSecure.gatewayCode: una respuesta detallada que describe el estado de autenticación
Debe observar response.3DSecure.summaryStatus para determinar cuál es el siguiente paso. Esto se resume en la tabla a continuación:
| 3DSecure.summaryStatus | Siguiente paso |
|---|---|
| AUTHENTICATION_SUCCESSFUL | La autenticación del pagador se realizó correctamente. Proceda con la operación de pago, incluyendo el 3DSecureID sobre la solicitud. |
| AUTHENTICATION_FAILED | Error en la autenticación del pagador. No debe proceder con la operación de pago. Esto va contra las reglas del esquema. |
| AUTHENTICATION_ATTEMPTED | Se intentó la autenticación del pagador, pero no se pudo completar. Proceda con la operación de pago, incluyendo el 3DSecureID sobre la solicitud. |
| AUTHENTICATION_NOT_AVAILABLE | Hubo un error. Proceda con la operación de pago, incluyendo el 3DSecureID sobre la solicitud |
Cuando el resultado de la operación Check 3DS Enrollment o Process ACS indica que se puede proceder con el pago, puede iniciar una operación Authorize o Pay. Incluya el 3DSecureId que proporcionó en la operación Check 3DS Enrollment en la solicitud. No es necesario incluir ninguno de los parámetros en el grupo de parámetros 3DSecure, dado que Mastercard Gateway utilizará el 3DSecureId para buscar los resultados de autenticación que almacenó cuando se le pidió que procesara el resultado de la autenticación. Mastercard Gateway transmitirá la información requerida al adquirente.
Otras opciones
Antes de comprobar la inscripción en 3DS, puede enviar una solicitud de cotización de tasa para Conversión dinámica de moneda (DCC) para recuperar la moneda del pagador y el monto del pedido de la moneda. Si el pagador acepta la oferta de DCC, entonces debe incluir la información de DCC en la solicitud Check 3DS Enrollment.
Referencia de API de DCC en Check 3DS Enrollment [REST] [NVP]
El HTML requerido para que el formulario utilizado redirija al pagador para la autenticación puede generarse mediante dos métodos de generación de página:
Simple: Mastercard Gateway genera el formulario HTML. El formulario completo se devuelve en la respuesta Verificar inscripción 3DS. Esta es la opción predeterminada.Customized: usted va a generar su propio formulario HTM personalizado, utilizando los parámetros proporcionados en la respuesta de Check 3DS Enrollment.
La respuesta a la operación Verificar inscripción 3DS incluirá la información requerida para la opción seleccionada.
(Opcional) Personalizar el formulario simple
Para personalizar el formulario simple generado, configure 3DSecure.authenticationRedirect.pageGenerationMode = SIMPLE en la solicitud de Check 3DS Enrollment y, a continuación, especifique los valores de uno o más parámetros:
3DSecure.authenticationRedirect.simple.expectedHtmlEncoding3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText3DSecure.authenticationRedirect.simple.redirectDisplayTitle
(Opcional) Generar su propio formulario personalizado
Para especificar que va a generar su propio formulario, configure 3DSecure.authenticationRedirect.pageGenerationMode = CUSTOMIZED en la solicitud Check 3DS Enrollment. La respuesta va a incluir los siguientes parámetros:
3DSecure.authenticationRedirect.customized.acsUrl: La URL del servidor de control de acceso (ACS) del emisor donde se puede autenticar al pagador.3DSecure.authenticationRedirect.customized.paReq: el mensaje de Solicitud de autenticación de pagador (PAReq) para enviar al ACS para iniciar la autenticación del pagador.
Incluya estos valores en su formulario, junto con la URL para devolver al pagador una vez que la autenticación se complete.
A continuación se muestra un formulario personalizado.
<!-- Populate the form action attribute with the value returned in the 3DSecure.authenticationRedirect.customized.acsUrl response parameter -->
<form name="3dsRedirect" action="[3DSecure.authenticationRedirect.customized.acsUrl]" method="POST" accept-charset="UTF-8">
<!-- Populate the mandatory PaReq parameter with the value returned in the 3DSecure.authenticationRedirect.customized.paReq response parameter. -->
<input type="hidden" name="PaReq" value="[3DSecure.authenticationRedirect.customized.paReq]"/>
<!-- Populate the mandatory TermUrl value with the URL to which you want the payer returned when the authentication process has completed. This should be the same value as supplied in the 3DSecure.authenticationRedirect.responseUrl parameter to the CHECK_ENROLLMENT request. -->
<input type="hidden" name="TermUrl" value="https://merchant.com/3ds/return"/>
<!-- The ACS will echo the contents of the mandatory MD parameter when the payer is returned to the URL specified in the TermUrl parameter. You can use this parameter to establish a link between the ACS request and response. -->
<input type="hidden" name="MD" value="[mdvalue]"/>
<input type="submit" value="Click here to continue" class="button">
</form>
Referencia de API de Personalizar formulario sobre Check 3DS Enrollment [REST] [NVP]
Si ha usado un MPI 3DS externo para autenticar al pagador, entonces debe transmitir la información sobre la autenticación en el grupo de parámetros 3DSecure de la operación Pay o Authorize.
Hay un campo obligatorio:
3DSecure.enrollmentStatus: indica si el titular de la tarjeta está inscrito para 3DS. Este campo es obligatorio.
Otros campos son opcionales, ya que si se los proporcionó o no el MPI externo de 3DS depende del estado de autenticación de la transacción:
3DSecure.authenticationStatus:indica si la autenticación 3DS del pagador fue exitosa.3DSecure.authenticationToken: el valor codificado base64 generado por el emisor de la tarjeta que se le puede devolver en el mensaje de respuesta de autenticación.3DSecure.acsEci: el indicador de comercio electrónico que se le puede devolver en el mensaje de respuesta de autenticación.3DSecure.xid: un identificador de transacción único para la autenticación de 3DS.
3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED, proporcione 3DSecure.authenticationToken.Referencia de API de 3DS preautenticado en Authorize [REST] [NVP]
Si desea recuperar los resultados de autenticación en cualquier etapa, utilice la operación Retrieve 3DS Result.
Preguntas frecuentes
Mastercard Gateway proporciona un resumen del estado de autenticación en el campo response.3DSecure.gatewayCode. Si desea derivar los valores de los campos de 3DS que se utilizan para procesar un pago, puede hacerlo desde el campo response.3DSecure.gatewayCode.
| response.3DSecure.gatewayCode | 3DSecure.enrollmentStatus | 3DSecure.authenticationStatus | Enviar operación de pago |
|---|---|---|---|
| CARD_ENROLLED | ENROLLED | - | (Continuar con la autenticación) |
| NOT_ENROLLED_NO_ERROR_DETAILS | NOT_ENROLLED | - | Sí |
| NOT_ENROLLED_ERROR_DETAILS_PROVIDED | NOT_ENROLLED | - | Sí |
| ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS | ENROLLMENT_STATUS_UNDETERMINED | - | Sí |
| ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED | ENROLLMENT_STATUS_UNDETERMINED | - | Sí |
| AUTHENTICATION_SUCCESSFUL | ENROLLED | AUTHENTICATION_SUCCESSFUL | Sí |
| AUTHENTICATION_ATTEMPTED | ENROLLED | AUTHENTICATION_ATTEMPTED | Sí |
| AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Sí |
| AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Sí |
| AUTHENTICATION_FAILED | ENROLLED | AUTHENTICATION_FAILED | No (no permitido) |
| MPI_PROCESSING_ERROR | ENROLLED | - | Sí |
| ACS_SESSION_TIMEOUT | ENROLLED | - | Sí |
| ERROR_PARSING_AUTHENTICATION_RESPONSE | ENROLLED | - | No (error) |
| INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE | ENROLLED | - | No (error) |
| CARD_DOES_NOT_SUPPORT_3DS | - | - | No (error) |
| ERROR_PARSING_CHECK_ENROLLMENT_REQUEST | - | - | No (error) |
| INVALID_DIRECTORY_SERVER_CREDENTIALS | - | - | Sí (sin datos de 3DS) |
| ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE | - | - | Sí (sin datos de 3DS) |
| ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER | - | - | Sí (sin datos de 3DS) |
Si es necesario, puede derivar el valor VERes.enrolled de 3DSecure.enrollmentStatus:
| VERes.enrolled | 3DSecure.enrollmentStatus |
|---|---|
| Y | ENROLLED |
| N | NOT_ENROLLED |
| U | ENROLLMENT_STATUS_UNDETERMINED |
También puede derivar el valor PAREs.status de 3DSecure.authenticationStatus:
| PARes.status | 3DSecure.authenticationStatus |
|---|---|
| Y | AUTHENTICATION_SUCCESSFUL |
| N | AUTHENTICATION_FAILED |
| U | AUTHENTICATION_NOT_AVAILABLE |
| A | AUTHENTICATION_ATTEMPTED |
Si proporcionó detalles de 3DS en una transacción, busque el pedido o la transacción en Merchant Administration. Vea los detalles del pedido, luego seleccione el vínculo para ver los detalles de autenticación.
Si desea ver los detalles de autenticación de una autenticación para la cual no realizó el pago (por ejemplo, la autenticación falló), utilice la opción Búsqueda de autenticación de pago en Merchant Administration.
El código de Estado de autenticación que se muestra al ver los detalles de autenticación en Merchant Administration se puede asignar a response.3DSecure.gatewayCode. Vea los Códigos nuevos en la tabla a continuación:
| Cliente de pago/Cliente de pago virtual | API | |
|---|---|---|
| Códigos nuevos | Códigos antiguos | response.3DSecure.gatewayCode |
| E | E | NOT_ENROLLED_NO_ERROR_DETAILS |
| Z | NOT_ENROLLED_ERROR_DETAILS_PROVIDED |
|
| C | C | CARD_DOES_NOT_SUPPORT_3DS |
| B | U | ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS |
| V | ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED |
|
| F | F | ERROR_PARSING_CHECK_ENROLLMENT_REQUEST |
| A | A | INVALID_DIRECTORY_SERVER_CREDENTIALS |
| W | U | ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE |
| D | D | ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER |
| I | I | MPI_PROCESSING_ERROR |
| P | P | ERROR_PARSING_AUTHENTICATION_RESPONSE |
| S | S | INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE |
| T | T | ACS_SESSION_TIMEOUT |
| X | U | AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS |
| U | AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED |
|
| Y | Y | AUTHENTICATION_SUCCESSFUL |
| N | N | AUTHENTICATION_FAILED |
| M | M | AUTHENTICATION_ATTEMPTED |
| R | CARD_ENROLLED |
|
Puede probar su integración para realizar la autenticación 3DS mediante el Mastercard Gateway, usando el Emulador ACS. Esto le permite seleccionar un resultado de Autenticación 3DS específico (devuelto en la respuesta de transacción en 3DSecure.authenticationStatus).
La prueba se admite para los siguientes esquemas de autenticación 3-D Secure:
- Mastercard SecureCode
- Verified by Visa
- American Express SafeKey
- J/Secure
- Diners ProtectBuy
Para probar la funcionalidad de autenticación 3-D Secure:
- Use una tarjeta de prueba inscrita 3-D Secure (consulte las tarjetas enumeradas en las secciones del adquirente específico) cuando envíe la solicitud de
CHECK_3DS_ENROLLMENTpara su perfil de pruebas del negocio. - Verifique que reciba una respuesta con
response.3DSecure.gatewayCode=CARD_ENROLLED. - Use el formulario suministrado en
3DSecure.authenticationRedirect.simple.htmlBodyContentpara redirigir el explorador del pagador a la página del Emulador ACS.El Emulador ACS redirige el explorador del pagador de vuelta a su sitio web y contiene el PARes.
- Envíe una solicitud de
PROCESS_ACS_RESULTcon el PARes en3DSecure.paRes. - Use el ID para esta autenticación 3-D Secure a través del Mastercard Gateway, proporcionado en
3DSecureIden una solicitud de transacción posterior (por ej.,PAYoAUTHORIZE).