Implementación de la Hosted Payment Page
Tiene dos opciones para implementar la Hosted Payment Page:
- La página integrada es un componente que se activa dentro de la página de pago existente de su sitio web.
- La página de pago es una página separada a la que se redirige al pagador desde su página de pago existente.
Una vez que se ha establecido una sesión de pago, el proceso de implementación de la Hosted Payment Page para Hosted Checkout consta de los siguientes pasos:
- Cree un objeto Checkout.
- Configure el objeto Checkout.
- Utilice el método apropiado del objeto de pago para iniciar el proceso de pago.
Además, puede definir devoluciones de llamada que se activan cuando el pagador realiza determinadas acciones durante el proceso de pago.
La implementación de la Hosted Payment Page se realiza en su aplicación o sitio web, utilizando la biblioteca Checkout JavaScript (JS).
Paso 1: Crear el objeto de pago
Una vez inicializada la sesión, debe hacer referencia al archivo checkout.min.js del servidor del motor de pagos en su página de pago. Esto coloca un objeto de pago en el ámbito global.
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Paso 2: Configurar el objeto Checkout
Llame a la función Checkout.configure() y pásele un objeto JSON que incluya el session.id devuelto por la operación Initiate Checkout anterior.
Checkout.configure({
session: {
id: '<your_initiate_checkout_ID>'
}
});
- En la API v67 o posterior, el objeto de sesión es el único campo permitido a través de configure(); todos los demás campos deben incluirse a través de INITIATE CHECKOUT.
- Los datos pasados en Checkout.configure() nunca sobrescriben los datos que ya proporcionó en la operación INITIATE CHECKOUT.
Paso 3: Iniciar el proceso de pago
Inicie el proceso de pago llamando a uno de los siguientes métodos del objeto de pago, según el tipo de Hosted Payment Page que esté implementando.
- Para mostrar la interacción de pago en una página incrustada:
Ejemplo
Checkout.showEmbeddedPage('#embed-target') - Para mostrar la interacción de pago en una página de pago:
Ejemplo
Checkout.showPaymentPage()
Ejemplo de código HTML para solicitar la página incrustada o de pago
<html>
<head>
<script src="https://ap-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>
Ejemplo de código HTML para utilizar el modo modal
<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://ap-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>
Paso 4: Implementación de devoluciones de llamada
Se proporcionan devoluciones de llamada para manejar eventos que pueden ocurrir durante la interacción de pago. El uso de devoluciones de llamada es opcional, pero si las necesita, debe definirlas en el cuerpo del mismo <script> que hace referencia a checkout.min.js.
Todas las devoluciones de llamada deben tener una implementación. Se invocan cuando se desencadena el evento relevante. El siguiente ejemplo de código muestra una devolución de llamada (activada si el pagador cancela el pago) definida e implementada en una página.
<script src="https://ap-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: Devoluciones de llamada básicas y devoluciones de llamada de redireccionamiento.
Devoluciones de llamada básicas
Se proporcionan devoluciones de llamada básicas para los siguientes eventos:
- cancel: cuando el pagador cancela la interacción del pago.
La cancel callback solo se puede utilizar con una página de pago, no funciona con una página integrada.
- 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.
Redirigir devoluciones de llamada
Dado que Hosted Checkout admite interacciones de pago que requieren que el pagador sea redirigido a otros sitios web para realizar el pago, como PayPal, se proporcionan devoluciones de llamada para gestionar qué sucede antes de la redirección y después del regreso 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 los datos necesarios para restaurar el estado de la interfaz de pago para que los utilice afterRedirect.
- 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 de pago 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 formulario guardados por saveFormFields(). úselo en su implementación de afterRedirect o implemente afterRedirect como Checkout.restoreFormFields().
Preguntas frecuentes
¿Qué debo hacer si Hosted Checkout devuelve un error?
Hosted Checkout puede devolver un número de errores de integración. Consulte Pasos para la prueba para obtener más información sobre pruebas y errores.
¿Por qué aparece una página de error en lugar de Hosted Payment Page?
Se muestra una página de error cuando se intenta realizar una solicitud de Hosted Checkout incorrecta. Entre las causas comunes de errores se incluyen las siguientes:
- Faltan campos obligatorios.
- Las URL proporcionadas en la solicitud no son absolutas.
¿Qué sucede si el pagador hace doble clic en el botón Pagar?
Si el pagador hace doble clic en el botón Pagar, es decir, envía el pago dos veces, la transacción no se repite con su banco ni con el del pagador.