Obligatorios:
Asegúrese de que su perfil de negocio esté habilitado para el servicio Hosted Checkout. Si no lo está, comuníquese con su proveedor de servicios. Para habilitar Hosted Checkout para el perfil del negocio, consulte el portal de Merchant Manager y la Guía de usuario de Merchant Manager.Opcional:
Si el pago se realiza correctamente, se recomienda que opte por el servicio de Notificaciones para recibir notificaciones por correo electrónico o Webhook. Al optar por este servicio, puede habilitar el motor de pagos para enviar notificaciones por correo electrónico al pagador en su nombre.Consejo:
Antes de comenzar con el proceso de integración de la funcionalidad Hosted Checkout, debe ver el apartado de Consejos y buenas prácticas.Para solicitar una interacción con Hosted Checkout, siga estos pasos:
Solicite una sesión de pago mediante la operación Initiate Checkout
.
La solicitud debe incluir datos de pago y de interacción, así como también las instrucciones para completar. El siguiente es un fragmento de código de muestra para la operación Initiate Checkout
.
curl https://evopaymentsmexico.gateway.mastercard.com/api/nvp/version/73 \ -d "apiOperation=INITIATE_CHECKOUT" \ -d "apiPassword=$PWD" \ -d "apiUsername=merchant.<your_merchant_id>" \ -d "merchant=<your_merchant_id>" \ -d "interaction.operation=AUTHORIZE" \ -d "interaction.merchant.name=<your_merchant_name>" \ -d "order.id=<unique_order_id>" \ -d "order.amount=100.00" \ -d "order.currency=USD" \ -d "order.description=<description_of_order>"
Una respuesta correcta a esta operación contendrá parámetros de session.id
y successIndicator
. Puede guardar el valor devuelto en el parámetro successIndicator
en el sistema de la tienda para verificar si el pago se realizó correctamente o no. Consulte Obtener el resultado del pago.
Consulte el archivo checkout.min.js en los servidores del motor de pagos. Esto colocará un objeto Checkout
dentro del alcance global.
<script src="https://evopaymentsmexico.gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Referencia de checkout.js[JavaScript]
Llame al método de Checkout.configure()
, usando un objeto JSON que incluye el session.id
devuelto y otros parámetros de solicitud.
Checkout.configure({ session: { id: '<your_initiate_checkout_ID>' } });
Checkout.configure()
nunca sobrescribirán los datos que usted proporcionó en la operación Initiate Checkout
.Inicie el proceso de pago llamando a uno de los siguientes procesos.
Checkout.showEmbeddedPage('#embed-target')
Checkout.showPaymentPage()
<html> <head> <script src="https://evopaymentsmexico.gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script> <script type="text/javascript"> function errorCallback(error) { console.log(JSON.stringify(error)); } function cancelCallback() { console.log('Payment cancelled'); } Checkout.configure({ session: { id: '<your_initiate_checkout_session_ID>' } }); </script> </head> <body> ... <div id="embed-target"> </div> <input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" /> <input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" /> ... </body> </html>
Checkout.configure()
, como:quantity : 300
quantity : function() { return 100 + 200 }
. Las funciones se ejecutan cuando se inicia el proceso de pago.
<html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous"> <title>Hello, world!</title> </head> <body> <h1>Hello, world!</h1> <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal"> Launch demo modal </button> <div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true"> <div class="modal-dialog" role="document"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="exampleModalLabel">Modal title</h5> <button type="button" class="close" data-dismiss="modal" aria-label="Close"> <span aria-hidden="true">×</span> </button> </div> <div class="modal-body" id="hco-embedded"> </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button> <button type="button" class="btn btn-primary">Save changes</button> </div> </div> </div> </div> <script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script> <script src="https://evopaymentsmexico.gateway.mastercard.com/static/checkout/checkout.min.js" ></script> <script> // Configure Checkout first Checkout.configure({ session: { id: "<your_initiate_checkout_ID>" } }) // after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded') $('#exampleModal').on('shown.bs.modal', function (e) { Checkout.showEmbeddedPage('#hco-embedded', () => { $('#exampleModal').modal() } // tell Checkout how to launch the modal ) }); $('#exampleModal').on('hide.bs.modal', function (e) { sessionStorage.clear(); // tell Checkout to clear sessionStorage when I close the modal }); </script> </body> </html>
Las devoluciones de llamada se proporcionan para administrar eventos que pueden ocurrir durante la interacción del pago.
El uso de las devoluciones de llamada es opcional, pero debe definir aquellas que necesita en el cuerpo de la misma etiqueta <script>
que consulta el archivo checkout.js.
Todas las devoluciones de llamada deben tener una implementación. Estas se invocarán cuando se inicie el evento pertinente.
<script src="https://evopaymentsmexico.gateway.mastercard.com/static/checkout/checkout.min.js" data-cancel="cancelCallback" data-beforeRedirect="Checkout.saveFormFields" data-afterRedirect="Checkout.restoreFormFields"> </script> <script> function cancelCallback() { confirm('Are you sure you want to cancel?'); // code to manage payer interaction } // or if you want to provide a URL: // cancelCallback = "someURL" </script>
Hay dos tipos de métodos de devolución de llamada:
Las devoluciones de llamada básicas se proporcionan para administrar los siguientes eventos:
cancel
: cuando el pagador cancela la interacción del pago.
error
: cuando se encuentra un error. complete
: cuando el pagador completa la interacción del pago. timeout
: cuando el pago no se completa dentro de la duración disponible para que el pagador realice el pago. Estas pueden ser funciones o URL. Si proporciona una URL en lugar de una función en una devolución de llamada, el pagador será redirigido a esta URL cuando se inicie el evento.
Dado que Hosted Checkout admite interacciones de pago que requieren redirigir al pagador a otros sitios web para continuar con el pago (por ejemplo PayPal), las devoluciones de llamada se proporcionan para administrar lo que sucede antes de la redirección y después de volver a Hosted Checkout para finalizar el procesamiento de la transacción.
beforeRedirect
: antes de que al pagador se le presente la interfaz de pago. Devuelve datos necesarios para restaurar el estado de la página, para que afterRedirect
la utilice.afterRedirect
: cuando el pagador regresa de completar la interacción del pago. Utiliza los datos guardados por beforeRedirect
para devolver el estado de la interfaz de pago guardada.El objeto Checkout
también proporciona dos funciones para ayudarle a implementar las devoluciones de llamada beforeRedirect
y afterRedirect
:
saveFormFields
: guarda todos los campos del formulario actual para que restoreFormFields
los utilice. Úselo en su implementación de beforeRedirect
o implemente beforeRedirect
como Checkout.saveFormFields
. restoreFormFields
: restaura los campos de los formularios guardados por saveFormFields
. Úselo en su implementación de afterRedirect
o implemente afterRedirect
como Checkout.restoreFormFields
. Referencia de checkout.js[JavaScript]
Una vez que la interacción de pago se completa, puede regresar al pagador al sitio de la tienda y presentar su propia página de recibo al pagador. También puede actualizar su sistema de compras con los detalles del pago.
Para regresar al pagador al sitio de la tienda, debe hacer lo siguiente:
interaction.returnUrl
en la operación Initiate Checkout
, O BIENcomplete
en la solicitud de Hosted Checkout. Esto se aplica tanto a las devoluciones de llamada básicas como a las de redireccionamiento. Consulte Devoluciones de llamada.El motor de pagos envía el resultado del pago en un parámetro resultIndicator
, que:
interaction.returnUrl
) utilizada para regresar al pagador al sitio de su tienda, O BIENcomplete
o se adjunta a la dirección URL proporcionada en la devolución de llamada de complete
.Usted puede determinar si el pago se realizó correctamente o no al comparar el parámetro resultIndicator
con el parámetro successIndicator
devuelto en la respuesta Initiate Checkout
. Una coincidencia indica que el pago se realizó correctamente.
resultIndicator
nunca debe usarse como número de recibo.Si se realiza correctamente, presente un recibo de pago al pagador en el sitio de la tienda y actualice el sistema de la tienda con los detalles del pago. Puede recuperar estos mediante la operación Retrieve Order
.
Los detalles del pago se registran en Merchant Administration, en la página Detalles del pedido y la transacción. Puede buscar el pago y además realizar las operaciones posteriores.
Si se suscribe a Reporting, puede descargar datos de pago de Hosted Checkout en un reporte con formato de Mastercard Payment Gateway.
Si se suscribe a las notificaciones por correo electrónico en Merchant Administration, recibirá una notificación por correo electrónico cada vez que se realice correctamente un pago.
Hosted Checkout le permite controlar la visualización de la información de su negocio y la interacción con el pagador usando la operación Initiate Checkout
.
URL | https://evopaymentsmexico.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session |
Método HTTP | POST |
{ "apiOperation": "INITIATE_CHECKOUT", "interaction": { "merchant": { "name": "The Company Co", "url": "https://www.merchant-site.com", "logo": "https://upload.wikimedia.org/wikipedia/commons/2/21/Verlagsgruppe_Random_House_Logo_2016.png" }, "displayControl": { "billingAddress": "MANDATORY", "customerEmail": "MANDATORY" }, "timeout": 1800, "timeoutUrl": "https://www.google.com", "cancelUrl": "http://www.google.com", "operation": "PURCHASE", "style": { "accentColor": "#30cbe3" } }, "billing": { "address": { "city": "St Louis", "stateProvince": "MO", "country": "USA", "postcodeZip": "63102", "street": "11 N 4th St", "street2": "The Gateway Arch" } }, "order": { "amount": "123.60", "currency": "EUR", "description": "This is the order description", "id": "ORDER-4142773a-ac2e" }, "customer": { "email": "peteMorris@mail.us.com", "firstName": "John", "lastName": "Doe", "mobilePhone": "+1 5557891230", "phone": "+1 1234567890" } }
interaction.merchant
se mostrarán en la página de recibo solo para la integración de la página de pago hospedado, no para la página incrustada. Puede personalizar la experiencia de pago con las siguientes opciones:
Esto incluye su logotipo, así como los datos de contacto.
Consulte: Todos los parámetros: Initiate Checkout para ver los detalles a continuación:
Después de recopilar las direcciones de facturación y de correo electrónico del pagador, puede visualizarlas y controlar su capacidad de edición mediante la configuración de los campos interaction.displayControl.billingAddress
e interaction.displayControl.customerEmail
en una de las siguientes opciones:
HIDE
: si no desea que Hosted Checkout muestre los campos.MANDATORY
: si desea que Hosted Checkout muestre los campos y haga obligatoria la introducción de datos para el pagador. OPTIONAL
: si desea que Hosted Checkout muestre los campos, pero permitir que el pagador decida no ingresar datos en ellos.READ_ONLY
: si desea que Hosted Checkout muestre los campos, pero no permitir que el pagador los edite.Después de recopilar los detalles de envío del pagador, puede visualizarlos mediante la configuración del campo interaction.displayControl.shipping
en una de las siguientes opciones:
HIDE
: si no desea que Hosted Checkout muestre los campos.READ_ONLY
: si desea que Hosted Checkout muestre los campos, pero no permitir que el pagador los edite.De forma predeterminada, el idioma que se muestra con Hosted Checkout se define a partir del explorador del pagador. Sin embargo, puede anular este comportamiento al especificar un identificador de idioma o etiqueta de idioma IETF, en el campo locale
; por ejemplo, en_US
, es
, fr_CA
. Si el idioma que especifica no es admitido por Mastercard Payment Gateway, Hosted Checkout aparece en el idioma más semejante.
De forma predeterminada, el tema establecido por defecto por su proveedor de servicios de pago controla la apariencia de Hosted Checkout. Si su proveedor de servicios de pago admite varios temas, puede elegir anular el tema predeterminado al proporcionar el campo interaction.style.theme
en su solicitud.
El tema disponible para usted en este momento es default
.
Se recomienda que incluya order.id
en su solicitud para identificar fácilmente un pago iniciado desde Hosted Checkout. Puede utilizar un identificador generado por su carrito de compras o ingresar uno propio. Sin embargo, asegúrese de que sea único.
Cuando un pagador elige pagar con su tarjeta, puede ingresar los detalles de la tarjeta de crédito o débito durante la interacción de pago. No obstante, si al menos uno de sus adquirentes admite tarjetas combinadas, es decir, tarjetas que se pueden utilizar como tarjeta de débito o crédito, el pagador deberá seleccionar el método de pago en la página de pago — Tarjeta de débito o tarjeta de crédito — para especificar el modo en que la tarjeta debe operar para este pago.
Para usar la autenticación 3-D Secure con su integración de Hosted Checkout, póngase en contacto con su proveedor de servicios de pago para habilitar los privilegios necesarios para su cuenta de negocio.
Para probar si su integración funciona con la autenticación 3-D Secure, puede usar su perfil de pruebas del negocio en el entorno de producción.
Utilice las siguientes tarjetas de prueba para probar la integración
Tipo de tarjeta | Estado de autenticación | Tarjeta de prueba |
---|---|---|
Mastercard | 3DS2 - Desafío | 5123450000000008 |
Mastercard | 3DS1 - No está inscrito para 3DS2, por lo que se recurre como alternativa a 3DS1 | 5506900140100305 |
Visa | 3DS2 - Desafío | 4440000009900010 |
Visa | 3DS1 - No está inscrito para 3DS2, por lo que se recurre como alternativa a 3DS1 | 4508750015741019 |
Para obtener más información sobre la autenticación, consulte Preguntas frecuentes sobre la autenticación.
EMV 3-D Secure (EMV 3DS) es un estándar global del sector diseñado para ayudar a negocios y emisores a autenticar transacciones sin tarjeta presente. La última generación de estándares del sector EMVCo, que se conoce como EMV 3-D Secure o EMV 3-D Secure 2.0, es un protocolo más robusto y ofrece una autenticación más segura que la versión actual (3-D Secure 1). La habilitación de EMV 3DS mejora su experiencia de pago digital gracias a la reducción del fraude, los falsos rechazos y la fricción innecesaria.
Hosted Checkout puede configurarse para proporcionar una experiencia de usuario que cumple con el Nivel AA de WCAG 2.0. Consulte las Pautas de WCAG 2.0 y asegúrese de que su sitio web se ajusta a esta norma técnica.
Agregue el atributo lang al elemento html.
<html lang="en"> <head></head> <body></body> </html>
Si tiene planes de pago configurados en su perfil de negocio, de forma predeterminada, todos los planes de pago de la configuración de negocio se mostrarán al pagador durante Hosted Checkout. Sin embargo, los planes de pago disponibles para el pagador estarán determinados por el número de tarjeta que este ingrese y la moneda del pedido.
Puede limitar los planes de pago disponibles en oferta al especificar restricciones en los planes de pago, según cada transacción. Esto resulta útil si desea asegurarse de que las opciones de pago ofrecidas al pagador cumplan con los criterios predefinidos, con lo cual se evita el procesamiento del pago si el pagador altera los datos de los planes de pago. Puede utilizar los siguientes campos en la solicitud para especificar las restricciones:
constraints.paymentPlans.supported[n]
: los planes de pago que se ofrecen para esta transacción.constraints.paymentPlans.numberOfPayments
: el número permitido de cuotas para el plan de pago.constraints.paymentPlans.numberOfDeferrals
: el número permitido de meses de diferimiento para el plan de pago.De forma predeterminada, los términos de pago para un plan de pago, si están disponibles, se mostrarán en Hosted Checkout. Puede ocultarlos al configurar interaction.displayControl.paymentTerms=HIDE
en Checkout.configure()
.
Para pagos mediante tarjetas de regalo y Automated Clearing House, Hosted Checkout solo admite verificación de los detalles del pago.
Para esto, configure interaction.operation=VERIFY
en la solicitud Initiate Checkout.
Hosted Checkout usa los métodos de verificación reconocidos por el adquirente configurado y los datos proporcionados en la solicitud.
Usted puede determinar si la operación de verificación se realizó correctamente o no al comparar resultIndicator
con successIndicator
.
Si la interacción no se realizó correctamente, Hosted Checkout muestra un mensaje donde se indica que la verificación no pudo realizarse y se solicita que el pagador vuelva a intentarlo.
Puede usar Hosted Checkout con cualquier fuente de transacción configurada en el perfil de negocio (Internet, centro de llamadas, pedido por teléfono, etc.).
Para esto, proporcione transaction.source
en la solicitud Initiate Checkout.
Si se solicita a Hosted Checkout un transaction.source
distinto a INTERNET
, las opciones de pago que requieren que el pagador esté presente no se admitirán.
Si no proporciona transaction.source
en la solicitud:
INTERNET
si se admite en el vínculo de negocio-adquirente.Puede controlar si se requiere que los pagadores proporcionen el Código de seguridad de la tarjeta para procesar el pago, al configurar interaction.displayControl.cardSecurityCode
, en la solicitud Initiate Checkout, en uno de los siguientes valores:
OPTIONAL
: si desea que Hosted Checkout muestre el campo de ingreso del código de seguridad de tarjeta, pero no es obligatorio completar este campo.MANDATORY
(predeterminado): si desea que Hosted Checkout muestre el campo de ingreso del Código de seguridad de la tarjeta y que sea obligatorio completarlo.Si está configurado para la autenticación 3-D Secure o un servicio de administración de riesgos, tiene la opción de ignorarlos, si así lo desea.
interaction.action.3DSecure=BYPASS
en la solicitud Initiate Checkout. El campo interaction.action.3DSecure
de la solicitud CREATE_CHECKOUT_SESSION
puede adoptar los siguientes valores:
risk.bypassMerchantRiskRules=ALL
en la solicitud Initiate Checkout. Para usar Click To Pay con su integración de Hosted Checkout, póngase en contacto con su proveedor de servicios de pago para habilitar los privilegios necesarios para su cuenta de negocio.
Click to Pay es una opción de pago en línea inteligente y sin contraseña que brinda una experiencia de pago rápida y fácil diseñada para hacer que el "pago como invitado" sea más rápido y fácil en todos los dispositivos. Click to Pay proporciona un flujo de pago estandarizado para todos los esquemas de tarjetas participantes. Click to Pay se basa en la especificación SRC de EMVCo y reemplaza a Masterpass, Visa Checkout y Amex Express Checkout.
Si está utilizando la página de pago del motor de pagos (Hosted Checkout), Click to Pay se ofrecerá automáticamente a sus pagadores si activó Click to Pay para su perfil del negocio.
Hay parámetros adicionales que se deben tener en cuenta al enviar la solicitud de Initiate Checkout para Click to Pay con Hosted Checkout.
Parámetros de Initiate Checkout para Click to Pay con Hosted Checkout:
Campo | Descripción | Obligatorio |
---|---|---|
interaction.country |
Para una interacción de SRC, el país de interacción determina el contenido específico del país que se presenta al pagador durante la interacción de SRC, como los Términos y condiciones. El valor que configuró con respecto a su perfil del negocio en el motor de pagos se utiliza de forma predeterminada. Agregue el campo interaction.country a la solicitud de Initiate Checkout si desea anular este valor para esta interacción. | Opcional |
interaction.locale |
Para una interacción de SRC, la configuración regional de la interacción determina el idioma de visualización. De forma predeterminada, se utiliza el idioma configurado en el explorador del pagador. Si el idioma del pagador no se puede determinar o no es compatible, se utiliza en_US. Si desea anular este valor, agregue el campo interaction.locale a la solicitud de Initiate Checkout. Actualmente, los idiomas admitidos son inglés (Reino Unido) (en_UK), español (España) (es_ES), francés (Canadá) (fr_CA), portugués (Brasil) (pt_BR) y chino (Hong Kong) (zh_HK). | Opcional |
merchant.name |
Proporcione su nombre comercial, como el nombre conocido por su pagador. El nombre puede aparecer durante la interacción de SRC. | Obligatorio |
merchant.url |
Proporcione la URL de su sitio web que utiliza el pagador. La URL puede mostrarse durante la interacción de SRC. | Obligatorio |
customer.email |
La dirección de correo electrónico del pagador siempre se recopilará durante la interacción de SRC. Si ya conoce la dirección de correo electrónico del pagador, agregue customer.email: "su dirección de correo electrónico del pagador" a la solicitud de Initiate Checkout para permitir que el pagador omita ingresar su dirección de correo electrónico durante la interacción de SRC. | Opcional |
Para obtener más información sobre Click To Pay, consulte las Preguntas frecuentes.
Antes de iniciar transacciones en producción, debe probar su integración para garantizar una funcionalidad correcta.
Antes de iniciar transacciones en producción, debe probar su integración para garantizar una funcionalidad correcta.
Hosted Checkout puede devolver un número de errores de integración. Consulte Pruebe su integración.
Aparecerá una página de error cuando se intente una solicitud de Hosted Checkout incorrecta. Entre las causas comunes de errores se incluyen las siguientes:
Si el pagador oprime dos veces el botón "Pagar", la transacción no se repetirá con su banco o el banco del pagador.
Sí, se admite EDGE 113.
El modelo de Hosted Checkout es seguro, ya que requiere que usted se autentique en el motor de pagos, y los detalles de pago recopilados en la página de pago se envían directamente del explorador del pagador al motor de pagos.
No hay restricciones sobre el tamaño del archivo o el ancho del logotipo. En cuanto a la altura, la recomendación mínima es de 144 px.
Sí, puede hospedar la imagen del logotipo en cualquier proveedor, sin embargo, es obligatorio que la URL sea segura (HTTPS). Si su proveedor hospedado no admite una URL segura, la siguiente es una lista de proveedores que pueden ofrecerle hospedaje HTTPS gratuito: https://www.google.com.au/search?q=secure+image+hosting+providers
Esta casilla de verificación solo está visible cuando se han llenado todos los campos obligatorios en la dirección de envío. Debe asegurarse de que el pagador los haya completado o de llenar usted mismo aquellos que falten (como por ejemplo shipping.country
, en caso de que no se realice el envío internacional de las mercancías).
Si desea ofrecer a sus clientes una buena experiencia móvil que incluya la optimización de su experiencia de Hosted Checkout en dispositivos móviles, le recomendamos agregar una metaetiqueta de "ventana gráfica" en la página de su sitio. Por ejemplo:
<meta name="viewport" content="width=device-width, initial-scale=1">
Tenga en cuenta que es importante elegir los valores de ventana gráfica correctos para sus páginas y probar su propio sitio con estos cambios.
Derechos de autor © 2023 Mastercard