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.

Si implementó originalmente una página Lightbox (con API v62 o anterior), su página de pago es un cuadro de diálogo modal que se muestra en la parte superior de su página de pago existente. Las versiones de API más nuevas no admiten directamente esta implementación, pero si está migrando a una versión de API más nueva, puede usar un modo modal, que le permite usar Lightbox como una extensión de la página incrustada.

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:

  1. Cree un objeto Checkout.
  2. Configure el objeto Checkout.
  3. 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.

Ejemplo

<script src="https://gateway-emea.americanexpress.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Si está habilitado para las operaciones de AUTHORIZATION y PAY, debe usar Hosted Checkout v52 o superior.

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.

Ejemplo

        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

Ejemplo



<html>
    <head>
<script src="https://gateway-emea.americanexpress.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

Ejemplo



<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://gateway-emea.americanexpress.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.

Ejemplo de devolución de llamada


<script src="https://gateway-emea.americanexpress.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.
Estas devoluciones de llamada se pueden definir como funciones, como en el ejemplo anterior, o como URL. Si proporciona una URL en lugar de una función en una devolución de llamada, el pagador es redirigido a esta URL cuando se activa el evento.

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 Copied to Clipboard

¿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.