- Pautas de integración
- Características soportadas (seguridad)
- Proteja su integración con contraseñas o certificados
Proteja su integración con contraseñas o certificados
Puede autenticarse en Mastercard Gateway mediante contraseñas o certificados SSL.
Autenticación de contraseña
Puede habilitar el acceso seguro a la DirectAPI de Mastercard Gateway e integraciones de Batch mediante contraseñas. La contraseña generada por el sistema es de 16 bytes, valor generado aleatoriamente y codificado como una cadena hexadecimal. Aunque tiene la longitud y la calidad suficientes para resistir una adivinación forzada, debe protegerse de la misma manera que las contraseñas de usuario y otros datos confidenciales.
Generar una contraseña para DirectAPI
Puede generar su contraseña de la API en Merchant Administration. Como prerrequisito, su perfil de negocio debe estar habilitado para la API, Batch y el privilegio "Usar autenticación con contraseña".
Para acceder a Merchant Administration, necesita sus credenciales de inicio de sesión. your payment service provider le proporcionará las credenciales de inicio de sesión de administrador cuando se haya registrado correctamente en el motor de pagos. Como administrador, puede crear un nuevo operador con permisos para generar la contraseña de la API.
- Inicie sesión en https://banamex.dialectpayments.com/ma con sus credenciales de inicio de sesión de administrador.
- Vaya a Admin > Operadores
- Cree un nuevo operador completando todos los campos obligatorios. Asigne el privilegio "Puede configurar ajustes de integración" para permitir que el operador genere la contraseña de la API.
- Cierre sesión en Merchant Administration y vuelva a iniciar sesión en Merchant Administration como el nuevo operador.
- Vaya a Admin > Ajustes de integración de la API de servicios web > Editar.
- Haga clic en Generar nueva y seleccione la casilla Habilitar el acceso a la integración a través de una contraseña.
- Esta es la contraseña de la API que utilizará para autenticar las solicitudes de API realizadas desde su servidor web al motor de pagos.
- Haga clic en Enviar.
Siempre debe tener al menos una contraseña generada y habilitada, pero puede tener hasta dos contraseñas configuradas. Por seguridad, debe cambiar la contraseña de manera periódica. Solo debe usarse una contraseña para configurar su aplicación, mientras la segunda funciona en suspensión para fines de rotación de contraseña.
Una vez generada la contraseña, debe incluirla en todas las solicitudes de transacción dirigidas al Mastercard Gateway. Si la solicitud se envía usando el protocolo REST-JSON, entonces la solicitud debe contener el ID de usuario y la contraseña en el encabezado de autenticación básico HTTP. Con NVP, debe proporcionar parámetros adicionales en la solicitud, apiUsername y apiPassword para usar la API.
Para autenticarse como negocio, el nombre (apiUsername para NVP y el ID de usuario para REST-JSON) y la contraseña (apiPassword para NVP y la contraseña para REST-JSON) deben contener 'merchant.<your gateway merchant ID>' y la contraseña generada por el sistema respectivamente.
Referencia de API de Contraseña [REST][NVP]
Autenticación de certificación
Tenga en cuenta que el nombre del host para la autenticación de certificación es diferente de https://banamex.dialectpayments.com/api. Comuníquese con your payment service provider para solicitar el nombre del host.
Con la autenticación de certificación, debe presentar un certificado para autenticarse ante Mastercard Gateway. Por lo general, se emiten certificados de una de muchas organizaciones que actúan como entidades de certificación (CA). Este modelo de autenticación es un componente de la infraestructura de clave pública (PKI), donde la seguridad se logra a través de confidencialidad, integridad, no rechazo y autenticación. La CA asegura que la clave pública adjunta al certificado es correcta, pertenece a la persona o entidad que se asegura (es decir, es ‘auténtica’) y no ha sido manipulada ni reemplazada por un tercero malintencionado.
El mecanismo de autenticación para la autenticación de certificación requiere que el cliente (su Servidor web) y el servidor (Servidor HTTP de Mastercard Gateway) presenten certificados para autenticarse. Esto se conoce como autenticación mutua, cuyo flujo de trabajo se ilustra a continuación.
Al conectarse con Mastercard Gateway mediante la autenticación de certificación, ocurre lo siguiente:
- El cliente solicita conexión con un recurso protegido del servidor. Esto tiene lugar para cada solicitud de transacción iniciada por el cliente.
- El servidor presenta su cadena de certificados al cliente.
- El cliente verifica el certificado del servidor mediante una tienda de confianza, la cual contiene las CA de raíz confiables. El cliente valida la ruta del certificado a un certificado raíz de CA confiable.
- Si todo está correcto, el cliente envía su cadena de certificación al servidor, la cual está contenida en una tienda clave.
- El servidor verifica el certificado del cliente mediante un completo conjunto de certificados de raíz confiables o aprobados por la CA que están cargados en el servidor. Se realizan las siguientes comprobaciones:
- Comprueba si el certificado está en formato de certificación X.509.
- Valida la ruta del certificado a un certificado raíz de CA confiable.
- Realiza comprobación de CRL u OCSP (Protocolo de estado de certificación en línea) para garantizar que el certificado no se haya revocado.
- Comprueba si el certificado no ha vencido.
Una vez que el Servidor HTTP ha validado correctamente el certificado cliente, toda la cadena de certificado cliente se pasa a DirectAPI para su verificación. Si no, el Servidor HTTP devuelve mensajes de error de certificado SSL estándar.
La verificación se produce en los niveles de Servidor HTTP y DirectAPI. El Servidor HTTP realiza una validación de certificación SSL y DirectAPI realiza una autenticación de certificado a nivel comercial. - DirectAPI realiza las siguientes comprobaciones:
- Extrae el nombre común de sujeto del certificado de cliente y confirma que coincida con el nombre común de sujeto registrada contra el negocio en la base de datos. El nombre común de sujeto del certificado debe contener el nombre comercial legal del negocio.
- Verifica que el certificado de cliente tiene una extensión Key-Usage, marcada crítica que incluye la autenticación de cliente como un uso permisible del certificado.
- Realiza una validación simple del certificado de cliente ante un certificado raíz de CA contenido en el conjunto de CA permitidas. Esto significa que la aplicación de DirectAPI debe contener el certificado raíz de CA que se usó para emitir y firmar el certificado de cliente.
El conjunto inicial de CA que se pueden permitir lo determina Mastercard.
- Comprueba si el certificado presentado coincide con el estado del perfil de negocio. Un perfil de producción solo aceptará certificados de producción, mientras que un perfil de prueba aceptará certificados de prueba o producción.
Si los pasos del 1 al 4 están correctos, entonces la autenticación de negocio seguramente será correcta, de lo contrario, la conexión se rechaza mediante la devolución de un mensaje de error correspondiente.
- Si todas las comprobaciones del paso 5 y 6 son correctas, entonces el servidor acepta la conexión y permite que la solicitud de operación proceda.
Puede elegir presentar su certificado de cliente o un certificado diferente para autenticarse cuando el pagador acceda a su aplicación. En esta interacción, su Servidor web actúa como servidor y el pagador como cliente. Integrarse con este mecanismo de autenticación puede entregar a sus pagadores la seguridad agregada de que están haciendo transacciones con una empresa legítima.
Antes de iniciar transacciones en producción con su certificado de producción, puede desarrollar y probar la autenticación de PKI con un certificado de prueba. Esto puede ser útil, por ejemplo, si no desea compartir el certificado de producción y la clave privada con un integrador web de terceros.
Es importante que el certificado que procure de la CA de su preferencia cumpla con los requisitos de implementación de certificación de Mastercard. Estos son algunos puntos clave que se deben considerar al procurar su certificado SSL.
- El certificado debe contar con formato de certificación X.509.
- El certificado debe tener una extensión Key-Usage marcada como crítica e incluir la autenticación de cliente como un uso permisible del certificado.
- El certificado debe ser emitido por una CA aprobada por Mastercard. Póngase en contacto con Mastercard para obtener una lista de CA aprobadas.
- El nombre común (CN) de sujeto del certificado debe contener el nombre de dominio completamente calificado (con o sin un comodín) del sitio web para el cual se está comprando el certificado.
- El campo de organización (O) de sujeto debe contener la organización del negocio.
Después de obtener el certificado de una CA de confianza, your payment service provider debe configurar su certificado de prueba y/o de producción en Administrador de negocios como parte de la configuración de todos los ajustes de la API para su perfil del negocio en el motor de pagos. Si se requiere, un certificado de negocio se puede vincular a varios perfiles de negocio desde el mismo negocio o entre negocios. Para obtener más información sobre cómo configurar certificados de negocio en Administrador de negocios, consulte la sección Configuración de la API de la Guía de usuario de Administrador de negocios.
El sitio controla la lista de certificados raíz aceptables que se usan para verificar certificados de negocio. Para permitir la verificación de certificado, el sistema recopila la versión PEM codificada del certificado de producción a través del Administrador de negocios. El Nombre común de sujeto se extrae del certificado y se verifica con respecto al Nombre común de sujeto del certificado presentado durante el protocolo de vínculo SSL.
Después de configurar el certificado con respecto a su perfil de negocio, debe realizar los siguientes pasos para instalar el certificado en su entorno.
- Deje la clave privada y el certificado disponibles para el software de cliente SSL que hace la conexión SSL con el Mastercard Gateway. Dependiendo del software, la clave privada, el certificado y la cadena de certificación asociada, es posible que deba convertir a un formato compatible. Por ejemplo, las claves privadas y los certificados a menudo se proporcionan en archivos de texto, en formato PEM con la clave privada protegida por una contraseña. En Java, estos archivos generalmente se cargan en una tienda de claves Java. Consulte su documentación de software para conocer los formatos compatibles.
En el caso de entornos Java y .NET, recomendamos que convierta los archivos PEM a PKCS12.
- En casi todos los casos, la CA emisora para su certificado también proporciona certificados adicionales conocidos como cadena de certificación. Debe proporcionar estos al Mastercard Gateway durante el protocolo de vínculo SSL para permitir que el motor de pagos valide su certificado. Su software de cliente SSL tendrá instrucciones sobre cómo y dónde colocar estos certificados.
- Una prueba sencilla para comprobar si tiene todos los certificados necesarios consiste en cargarlos en un explorador web como Internet Explorer, Firefox o Safari, navegar hasta la URL de Check Gateway de DirectAPI del motor de pagos y recuperar el estado del motor de pagos. Si los certificados se cargan correctamente, acceder a la URL de Check Gateway provocará que el explorador le pida seleccionar o aceptar el certificado que se usará para conectarse con el motor de pagos. Si el explorador se lo pide y se logra una conexión satisfactoria, obtendrá la siguiente respuesta: {status: "OPERATING"}.
Es posible que desee cambiar del certificado existente a un nuevo certificado por diversos motivos. Por ejemplo, actualizar el certificado por un cambio de nombre de la empresa o pasar de un certificado de prueba a uno de producción.
Para pasar a un nuevo certificado, your payment service provider debe agregar el nuevo certificado como certificado principal, mientras que el certificado anterior se convierte en un certificado adicional. Puede tener uno o más certificados adicionales. Los negocios configurados para usar el nuevo certificado pueden autenticarse ante DirectAPI mediante el certificado antiguo o el nuevo. Se supone que esta sea una configuración interina hasta haber actualizado todas las integraciones para usar el nuevo certificado. Para obtener más información sobre cómo agregar certificados adicionales, consulte la sección Configuración de API en la Guía del usuario de Merchant Manager.
Autenticación con sesión
La autenticación de sesión utiliza la sesión de pago del motor de pagos, un contenedor temporal de campos de solicitud, para autenticar el negocio. Debido a que un negocio autenticado (mediante autenticación con contraseña o con certificado) crea la sesión de pago, el pagador puede usarla para interacciones del motor de pagos, como la realización de operaciones de autenticación.
Este mecanismo de autenticación permite que los pagadores proporcionen sus detalles de pago directamente al motor de pagos. Los datos del pagador se obtienen mediante una interacción del lado cliente con el motor de pagos, ya sea a través del explorador del pagador o de una aplicación de su dispositivo móvil. Ofrece un modelo sencillo de integración para obtener de forma segura los datos necesarios del pagador, ya que las solicitudes de API al motor de pagos se realizan directamente de parte del cliente y no del servidor.
Utiliza un mecanismo básico de autenticación HTTP (similar a la autenticación con contraseña), en el que debe proporcionar 'merchant.<your gateway merchant ID>;> en la parte de ID de usuario y el ID de sesión en la parte de contraseña.
Para usar este tipo de autenticación:
- Cree una sesión enviando una solicitud Create Session de API desde su servidor al servidor del motor de pagos. Esta operación devuelve un ID de sesión.
- Envíe la solicitud Update Session mediante autenticación con sesión para agregar cualquier dato pertinente a la sesión creada en el paso 1.
- Proporcione la sesión al pagador.
Transacciones admitidas
Las siguientes operaciones admiten autenticación mediante un ID de sesión.
- Update Session
- Initiate Authentication
- Authenticate Payer
Campos de entrada del pagador y salida del pagador
En las interacciones con el motor de pagos autenticadas con sesión, el pagador se restringe a un subconjunto de campos dentro de una operación API. Estos se conocen como campos de entrada del pagador. Si proporciona campos que no sean campos de entrada del pagador en una solicitud autenticada con sesión, la solicitud se rechaza. Por ejemplo, el pagador no puede enviar datos como el monto del pedido.
De manera similar a los campos de entrada del pagador, el motor de pagos permite la devolución de solo ciertos campos en la respuesta para una interacción con el motor de pagos autenticada con sesión. Estos se conocen como campos de salida del pagador. Solo se devuelven los campos que deben mostrarse a un pagador en un explorador o una aplicación para realizar una transacción. Por ejemplo, no se devuelven los datos confidenciales de seguridad como el ID de sesión.
Update Session
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- browserPayment.preferredLanguage
- correlationId
- customer.dateOfBirth
- customer.email
- customer.firstName
- customer.lastName
- customer.mobilePhone
- customer.nationalId
- customer.phone
- customer.taxRegistrationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.fingerprint
- device.hostname
- device.ipAddress
- device.mobilePhoneModel
- gatewayEntryPoint
- locale
- merchant
- order.id
- order.walletProvider
- session.version
- shipping.contact.email
- shipping.contact.firstName
- shipping.contact.lastName
- shipping.contact.mobilePhone
- shipping.contact.phone
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.mobileWallet.emv.emvData
- sourceOfFunds.provided.card.nameOnCard
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.provided.card.prefix
- sourceOfFunds.provided.card.securityCode
- sourceOfFunds.token
- sourceOfFunds.type
- transaction.acquirer.customData
- transaction.acquirer.traceId
- transaction.id
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.amount
- order.currency
- order.customerNote
- order.customerReference
- order.invoiceNumber
- result
- session.updateStatus
- session.version
Initiate Authentication
- apiOperation
- correlationId
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.number
- sourceOfFunds.token
- sourceOfFunds.type
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.redirect.customized.3DS.methodPostData
- authentication.redirect.customized.3DS.methodUrl
- authentication.redirectHtml
- authentication.version
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
Authenticate Payer
- apiOperation
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- correlationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.ipAddress
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.securityCode
- authentication.3ds2.acsReference
- authentication.3ds2.challenge.signedContent
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.3ds2.sdk.interface
- authentication.3ds2.sdk.timeout
- authentication.3ds2.sdk.uiType
- authentication.payerInteraction
- authentication.redirect.customized.3DS.acsUrl
- authentication.redirect.customized.3DS.cReq
- authentication.redirect.domainName
- authentication.redirectHtml
- authentication.version
- correlationId
- encryptedData.ciphertext
- encryptedData.nonce
- encryptedData.tag
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
Protección de la información del pagador mediante SSL
Todos los sitios web que recopilan información confidencial deben proteger los datos que pasan entre el explorador de Internet del pagador, la aplicación y Mastercard Gateway.
SSL es una tecnología de seguridad que se usa para proteger el servidor web en transacciones de explorador de Internet. Esto incluye proteger cualquier información (como el número de tarjeta de crédito del pagador) transmitida por un explorador de Internet a un servidor web (como su aplicación "Shop & Buy"). SSL protege los datos enviados por Internet de que no sean interceptados ni vistos por destinatarios no intencionados.
Al implementar el Direct Payment, debe asegurarse de que su aplicación presente un formulario seguro que use SSL. También debe considerar el uso de un formulario seguro en su aplicación al recopilar información confidencial como direcciones del pagador.
¿Cómo saben mis pagadores si mi sitio utiliza SSL?
Cuando un pagador se conecta a su aplicación con SSL, verá que http:// cambia a https:// y también aparecerá un pequeño candado amarillo en el explorador de Internet, por ejemplo:
Siempre que un explorador de Internet se conecte a un servidor web (sitio web) por https://, significa que la comunicación con Mastercard Gateway será cifrada y segura. Puede alertar a sus pagadores en relación con este hecho para que sepan qué buscar cuando hacen transacciones en su sitio web.
Tabla de referencia de diferencias clave entre modelos de seguridad
En la siguiente tabla se describen algunas diferencias clave entre modelos de autenticación de contraseña y de certificación, con la intención de ayudarlo a elegir la solución de autenticación que mejor cumple los requisitos de autenticación de su negocio.
| Autenticación de contraseña | Autenticación de certificación | |
| Cuándo usar |
Con empresas pequeñas, donde una autenticación sencilla cumple los requisitos. | Con empresas grandes, donde el costo de infraestructura para implementar PKI es mínimo frente a la seguridad que se obtiene al usar un nivel de autenticación más alto. |
| Habilidades técnicas requeridas |
Requiere conocimientos de autenticación HTTP básica | Requiere conocimientos de autenticación mutua y PKI con Entidades de certificación |
| Facilidad de integración |
Fácil de integrar | Configurar el archivo keystore y otra infraestructura puede sumarse a la complejidad de la integración. |
| Nivel de autenticación | Moderado | Alto |
| Costo | El método de autenticación menos costoso. | Implica costo adicional, como el costo de suscripción a la entidad de certificación para emitir los certificados SSL. |
| Beneficios | Ideal para negocios más pequeños, donde el costo de integración es un factor importante y los modelos comerciales no requieren niveles de seguridad más altos. | La autenticación mutua SSL proporciona seguridad muy alta y se considera una mejor práctica de la industria. Optimiza el rendimiento de autenticación al usar la conexión SSL existente, la cual, por lo general, se crea de todas maneras. El costo adicional de enviar el certificado de cliente es mínimo. |
| Desventajas | La contraseña se incrusta como cleartext en el encabezado de autenticación HTTP y solo debe mandarse por SSL. Mastercard Gateway solo acepta conexiones protegidas por SSL, por lo tanto protege la contraseña de divulgación; sin embargo, es muy importante para la seguridad de la conexión que se realice una autenticación de servidor adecuada para evitar una divulgación accidental ante servidores no autorizados. | Ninguno |
| Compatibilidad con el uso compartido de credenciales en varios perfiles de negocio | No puede compartir contraseñas en varios perfiles de negocio | Le permite compartir un ID de conjunto de certificados con varios perfiles de negocio dentro y en MSO (basado en privilegios). |