JS HtechPay

Descripción

La siguiente biblioteca se encarga de incorporar la carta de pago directamente en la estructura de la página web del comercio, lo que permite la visualización y la interacción del usuario con la pasarela de pago de forma integrada. Este enfoque ayuda a mantener la coherencia visual y funcional del sitio, proporcionando una transición sin inconvenientes entre la navegación habitual del usuario y el proceso de pago.

Esta biblioteca no solo facilita la inserción de la carta de pagos, sino que va más allá al priorizar la seguridad en todos los aspectos del proceso. Desde el cifrado de datos hasta el cumplimiento de estándares como PCI-DSS, se garantiza una integración segura y confiable que cumple con las más estrictas normas de seguridad de la industria, proporcionando tranquilidad tanto a su comercio como a los usuarios finales.

Además de su enfoque en la seguridad, la biblioteca proporciona formas de comunicación claras y sencillas para que el comercio obtenga todos los datos necesarios de las transacciones y que su comercio personalice y responda a datos clave, como el estado de la transacción y/o eventos que suceden dentro de la carta de pago. Esta flexibilidad permite una mayor personalización y adaptación del flujo de trabajo de pago de acuerdo con las necesidades específicas de su comercio, mejorando así la versatilidad y la experiencia del usuario.

📘
Para una versión UMD desde un CDN para cargar la biblioteca sin un bundler ver más abajo.

Requerimientos

De acuerdo con nuestra Política de soporte de versiones, actualmente admitimos todas las versiones LTS de Node.js 18+.

Instalación

npm install htech-pay

Configuración básica

 await htechPay(
          "id", //id generado
          {
            environment: "stage", // Ambiente de trabajo.
            onViewForm: () => {
              // Evento lanzado en cuanto carga la carta de pago.
              console.log("El formulario está visible");
            },
            onPaymentResult: (result) => {
              //Evento en devuelve el resulado de la transaccion.
              console.log("Resultado del pago:", result);
            },
          },
        );

Uso

Variables y funciones de configuración.

Variable	Tipo	Valores	Descripción
id	string		Id de transacción.
eviroment	string	stage / prod	Ambiente de trabajo.
type	string	widget / default / null	Tipo o diseño de la carta de pago, si no se agrega tipo se mostrara el diseño por defecto (default).
onViewForm	función		Se ejecuta al cargar el formulario.
onPaymentResult	función		Devuelve el resultado de la transacción.
theme	string	dark / default / null	Indica el tema que rederiza la carta de pago, el tipo widget no contiene un tema.
isPaymentToken	boolean	true / false	Variable que indica si el pago se realizará con un ID que contiene un token de una tarjeta guardada.
onClose	función		Se ejecuta si el usuario cierra el modal donde se solicita el cvv en el tipo por defecto (default)

Variables y funciones de implementación

Variable	Tipo	Descripción
mount	función	Función que monta el formulario. Recibe el ID del contenedor donde se montará.
destroy	función	Función que desmonta el formulario.
validateForm	función	Función que retorna si existen errores en los campos de la carta de pago y si la carta de pago es valida.
processPayment	función	Función que ejecuta el proceso de pago y retorna el resultado de la transacción.
validateFormCvv	función	Función que retorna si existen errores en el input del cvv, este input se utiliza unicamente en el pago con token con tipo widget.
processPaymentToken	función	Función que ejecuta el proceso de pago de un id con token y retorna el resultado de la transacción.

onPaymentResult

Función encargada de devolver el resultado de la transacción. La función onPaymentResult puede utilizarse en cualquier caso de uso; siempre contendrá el resultado de la transacción, sin importar el tipo de formulario o el tipo de pago.

Los valores devueltos son:

Variable	Tipo	Descripción
amount	string	Monto de la transaccón
status	string	Estatus de la transaccion approved = Pago exitoso rejected = Pago rechazo
currency	string	Código de la moneda cobrada
referenceNumber	string	Número de referencia de la transacción procesada con el banco hecha por nuestro sistema.
authorizationNumber	string	Numero de autorización de la transacción
card	object	Objeto que contiene el token con el que se realizó la transacción. (Solo aplica en pago con token)
id	string	Id de la transacción

📘
La información cargada en los formularios va acorde al id generado.

mount

La función mount se encarga de montar el formulario de pago dentro de un contenedor del DOM proporcionado por el integrador. Recibe como parámetro un selector CSS en formato string (por ejemplo, "#container") o directamente un elemento del DOM.

Si se proporciona un string, la función intentará localizar el elemento utilizando document.querySelector. Si se proporciona un elemento del DOM, lo utilizará directamente como punto de montaje.

En caso de que el contenedor no exista o no pueda encontrarse, la función lanzará un error indicando que no fue posible montar el formulario.

Una vez validado el contenedor, el iframe del formulario de pago será adjuntado como hijo de dicho elemento.

Esta implementación permite integrarse con cualquier framework o aplicación JavaScript que tenga acceso al DOM.

<div id="form-container"></div>

_htechPay.mount("#form-container");

destroy

La función destroy desmonta el formulario de pago del DOM y realiza la limpieza de los recursos internos

Ejemplo de uso basico

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>HtechPay</title>
  </head>
  <body>
    <!-- En este contenedor se montara el componente de htechPay -->
    <div id="form-container"></div>

    <script type="module">
      import { htechPay } from "htech-pay"; // importar librería htechPay.
      let _htechPay;

      async function setup() {
        _htechPay = await htechPay(
          "id", //id generado
          {
            environment: "stage", // Ambiente de trabajo.
            onViewForm: () => {
              // Evento lanzado en cuanto carga la carta de pago.
              console.log("El formulario está visible");
            },
            onPaymentResult: (result) => {
              //Evento en devuelve el resulado de la transaccion.
              console.log("Resultado del pago:", result);

              // Desmonta el componente de htechPay después del resultado.
              _htechPay.destroy(); //Funcion para desmontar el componente de htechPay.
            },
            theme: "", //Variable para indicar el tema.
          }
        );

        // Monta el iframe dentro del div
        _htechPay.mount("#form-container");
      }

      setup();
    </script>
  </body>
</html>

Ejemplo cambio de tema

📘
Recomendación: si se requiere alternar cualquier valor de configuración, por ejemplo, el tema se recomienda desmontar el componente de htechPay y volver a ejecutar la configuración como en el siguiente ejemplo.

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>HtechPay</title>
  </head>
  <body>
  
    <button id="btn-theme">default</button>
    <!-- Boton para cambio de tema -->
    <div id="form-container"></div>

    <script type="module">
      import { htechPay } from "htech-pay"; // importar funcion htechPay
      const themeBtn = document.getElementById("btn-theme"); // Varible boton
      let theme = "";

      let _htechPay;

      async function setup() {
        _htechPay = await htechPay(
          "id", //id generado
          {
            environment: "stage",
            onViewForm: () => {
              console.log("El formulario está visible");
            },
            onPaymentResult: (result) => {
              console.log("Resultado del pago:", result);
              _htechPay.destroy(); 
            },
            theme, //Variable para indicar el tema
          }
        );

        // Monta el iframe dentro del div
        _htechPay.mount("#form-container");
      }

      setup();

      function resetForm() {   //Funcion para resetear la configuracion de htechPay
        _htechPay?.destroy(); //Funcion para desmontar el componente de htechPay
        setup();  //Actualizar configuracion y volver a montar el componente de htechPay
      }

      themeBtn.addEventListener("click", () => {  //Funcion para cambiar el valor del tema
        theme = theme === "" ? "dark" : "";
        themeBtn.textContent = theme || "default";
        resetForm();
      });
    </script>
  </body>
</html>

Tipo widget

El tipo widget es un diseño más minimalista, pequeño y adaptable para interfaces reducidas. Se compone de un input que contiene los campos necesarios para la transacción de la orden generada.

Al tratarse de un diseño reducido, se exponen funciones para realizar la transacción, ya que este tipo no cuenta con un botón de pago, como sucede en el diseño por defecto.

Configuracion para tipo widget

await htechPay(
          "id", // Id de la orden
          {
            environment: "stage", // ambiente
            type: "widget",
          },
        );

validateForm

Función que retorna si existen errores en los campos de la carta de pago y si la carta de pago es válida

 const validation = await _htechPay.validateForm();

Valores del objeto

Valor	Tipo	Descripción
IsValid	Boolean	Valor que indica si los campos ingresados en la carta de pago son válidos
errors	object	Devuelve los campos indicando cual contiene errores, el valor true indica que el campo contiene errores.

processPayment

Función encargada de ejecutar la transacción al igual que el evento onPaymentResult tambien devuelve el resultado de la transacción.

Es recomendable usar en conjunto con la función validateForm

const validation = await _htechPay.validateForm();

if (validation.isValid) {
    const paymentResult = await _htechPay.processPayment();
  }

Valores de retorno de la funcion processPayment

Variable	Tipo	Descripción
amount	string	Monto de la transaccón
status	string	Estatus de la transaccion approved = Pago exitoso rejected = Pago rechazo
currency	string	Código de la moneda cobrada
referenceNumber	string	Número de referencia de la transacción procesada con el banco hecha por nuestro sistema.
authorizationNumber	string	Numero de autorización de la transacción
id	string	Id de la transacción

Ejemplo de uso

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>HtechPay - Widget Example</title>
    <style>
      body {
        font-family: Arial, sans-serif;
      }

      #payButton {
        margin-top: 20px;
        padding: 10px 20px;
        font-size: 16px;
        cursor: pointer;
      }

      #payButton:disabled {
        opacity: 0.6;
        cursor: not-allowed;
      }

      #result {
        margin-top: 20px;
        background: #f4f4f4;
        padding: 15px;
        white-space: pre-wrap;
      }
    </style>
  </head>

  <body>
    <h1>Pago con HtechPay (Widget)</h1>

    <!-- Contenedor donde se montará el iframe -->
    <div id="form-container"></div>

    <!-- Botón para procesar pago -->
    <button id="payButton">Pagar</button>

    <!-- Resultado -->
    <div id="result"></div>

    <script type="module">
      import { htechPay } from "htech-pay"; // importar librería htechPay.

      let _htechPay;

      const payButton = document.getElementById("payButton");
      const resultContainer = document.getElementById("result");

      function showLoading() {
        payButton.disabled = true;
        payButton.innerText = "Procesando...";
      }

      function hideLoading() {
        payButton.disabled = false;
        payButton.innerText = "Pagar";
      }

      async function setup() {
        _htechPay = await htechPay(
          "15628012-c8fb-4871-bd48-440a5da1a824", // ID de la orden
          {
            environment: "qa",
            type: "widget",
          },
        );

        _htechPay.mount("#form-container");
      }

      payButton.addEventListener("click", async () => {
        if (!_htechPay) return;

        // Validar formulario
        const validation = await _htechPay.validateForm();

        if (!validation.isValid) {
          console.log("Errores:", validation.errors);
          return;
        }

        if (validation.isValid) {
            showLoading();
            //Ejecutar transaccion 
            const paymentResult = await _htechPay.processPayment();
            //Mostrar resultado
            resultContainer.textContent = JSON.stringify(paymentResult, null, 2);
            hideLoading();
            //Quitar formulario
           _htechPay.destroy();
        }
      });

      setup();
    </script>
  </body>
</html>

Pago con token

El pago con token se realiza mediante un ID que contiene el token de una tarjeta guardada. Si es necesario solicitar el CVV, este se pedirá al usuario. Para el tipo widget, se mostrará un input con el mismo estilo que la tarjeta de pago de este tipo. Para el tipo por defecto, se mostrará un modal donde se solicitará el CVV.

Configuracion

await htechPay(
          "id", // Id de la orden
          {
            environment: "stage", // ambiente
            type: "widget", // tipo de formulario a mostrar
            isPaymentToken: true
          },
        );

Pago con Token con tipo por defecto

Para el pago con token en el tipo por defecto, al montar el componente con la configuración correspondiente, si es necesario solicitar el CVV para la transacción, se abrirá un modal donde se pedirá este valor. Una vez que el usuario ingrese la información y haga clic en el botón de confirmar CVV, se iniciará la transacción y el resultado será devuelto en la función onPaymentResult.

Para este caso tambien se ejecuta la funcion onClose si el usuario cierra el modal donde se solicta el cvv

Ejemplo de configuración

await htechPay(
          "id",
          {
            environment: "stage",
            isPaymentToken: true,
            onClose: () => {
            console.log("El usuario dio click a cerrar");
              }
          },
        );

Pago con Token con tipo widget

Para el pago con token de tipo widget, se exponen 2 funciones primordiales validateFormCvv y processPaymentToken .

validateFormCvv

Función que retorna si existen errores en los campos del input del cvv y si el valor es válido.

 const validation = await _htechPay.validateFormCvv();

Valores del objeto.

Valor	Tipo	Descripción
IsValid	Boolean	Valor que indica si los campos ingresados en la carta de pago son válidos
errors	object	Devuelve los campos indicando cual contiene errores, el valor true indica que el campo contiene errores.

processPaymentToken

Función encargada de ejecutar la transacción del pago con token y al igual que el evento onPaymentResult devuelve el resultado de la transacción.

Es recomendable usar en conjunto con la función validateFormCvv

const validation = await _htechPay.validateFormCvv();

if (validation.isValid) {
    const paymentResult = await _htechPay.processPaymentToken();
  }

Valores de retorno de la funcion processPaymentToken

Variable	Tipo	Descripción
amount	string	Monto de la transaccón
status	string	Estatus de la transaccion approved = Pago exitoso rejected = Pago rechazo
currency	string	Código de la moneda cobrada
referenceNumber	string	Número de referencia de la transacción procesada con el banco hecha por nuestro sistema.
authorizationNumber	string	Numero de autorización de la transacción
card	object	Objeto que contiene el token con el que se realizó la transacción,
id	string	Id de la transacción

❗️
Si existe un error en la configuración de la carta de pago, se mostrará un mensaje de Configuration error en la consola del navegador.
Por ejemplo, puede producirse un error si se utiliza un ID de pago con token mientras la variable isPaymentToken está configurada en false.

Versión UMD desde un CDN

Si se desea cargar la biblioteca sin un bundler, también se expone el archivo umd desde la siguiente URL.

https://unpkg.com/htech-pay/dist/htechPay.umd.js

Ejemplo

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>HtechPay</title>
  </head>
  <body>
    <!-- Contenedor donde se montará el componente de HTechPay -->
    <div id="form-container"></div>

    <!-- Cargar la versión UMD de la biblioteca desde un CDN -->
    <script src="https://unpkg.com/htech-pay/dist/htechPay.umd.js"></script>

    <script>
      let _htechPay;

      async function setup() {
        //  Se llama al objeto global de HtechPay
        _htechPay = await HtechPay.htechPay(
          "id", // ID generado
          {
            environment: "stage",
            onViewForm: () => console.log("El formulario está visible"),
            onPaymentResult: (result) => {
              console.log("Resultado del pago:", result);
              _htechPay.destroy();
            },
            theme: "",
          }
        );

        // Montar el iframe dentro del div
        _htechPay.mount("#form-container");
      }

      setup();
    </script>
  </body>
</html>

Las demas configuraciones funcionan igual que la version de npm, solo cambia su forma de cargar la biblioteca.

Link NPM

https://www.npmjs.com/package/htech-pay