Checkout Elements

Bajo código Checkout Elements te permite aceptar pagos directamente dentro de tu sitio web sin que el usuario perciba que salió de él. A diferencia del Payment Link, aquí el checkout se monta como un componente dentro de tu propia página. Todas las interfaces están desarrolladas por PayCode, pero tu cliente nunca abandona tu portal.

El proceso tiene 3 pasos

Autenticarte

Llama a /Api/v2/auth/login con tu API Key para obtener un token de sesión. Consulta la sección Autenticación y seguridad para ver el detalle completo.

Obtener el hash de la transacción

Crea un link de pago usando /api/v2/links-pago/crear_link. La respuesta incluye el hash que necesitas para el siguiente paso.

Montar el componente de checkout en tu página

Usa el hash para inicializar el componente de checkout directamente en tu sitio.

Obtener el hash de la transacción

El hash es el identificador único del link de pago. Se genera al crear un link de pago mediante el endpoint /api/v2/links-pago/crear_link, el mismo utilizado en Link de pago. La respuesta incluye la URL del link de pago, desde la cual puedes obtener el hash con el siguiente formato:

https://dev-checkout.paycode.com.mx/<hash-code>

Debes extraer el valor que viene al final de ese link. Ese es el hash que usarás para inicializar el componente.

Consulta la sección Link de pago para ver el detalle completo de cómo crear un link de pago y obtener el hash.

Montar el componente

1. Importar la librería

Agrega el script al <head> de tu aplicación antes de inicializar el componente. Se recomienda que la librería esté disponible de forma global. Usa la URL correspondiente a tu entorno:

<script src="https://paycode-elements.s3.us-east-2.amazonaws.com/v0.1.0/paycode-dev.umd.js"></script>

<script src="https://paycode-elements.s3.us-east-2.amazonaws.com/v0.1.0/paycode.umd.js"></script>

2. Inicializar el componente

Una vez importada la librería, inicializa el componente con el hash que obtuviste en el paso anterior. El flujo es el siguiente:

Crea una instancia de Paycode
Llama a elements() para obtener el objeto de elementos
Usa create("checkout-modal", { ... }) para montar el checkout con la configuración que necesites

<head>
  <script>
    document.addEventListener("DOMContentLoaded", () => {
      document
        .getElementById("checkoutButton")
        .addEventListener("click", () => {
          const paycode = new Paycode();
          const elements = paycode.elements();
          elements.create("checkout-modal", {
            hash: "XNP-xxx-kKu",        // Reemplaza con el hash de tu link de pago
            mountSelector: "#checkout",  // Elemento HTML donde se renderiza el checkout
            onPaymentSuccess: (redirectUrl, data) => {
              // El pago fue aprobado
              // redirectUrl: URL a la que redirigir al usuario
              // data.cardNumber: últimos dígitos de la tarjeta usada
              console.log("Pago exitoso. Redirigiendo a:", redirectUrl);
            },
            onPaymentReject: (error) => {
              // El pago fue rechazado
              console.error("Pago rechazado:", error);
            },
            onError: (error) => {
              // Ocurrió un error en el proceso
              console.error("Error:", error);
            },
          });
        });
    });
  </script>
</head>
<body>
  <div id="checkout" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" />
  <button id="checkoutButton">Abrir checkout</button>
</body>

Propiedades de `create`

Propiedad	Tipo	Requerida	Descripción
`hash`	string	Sí	Identificador único del link de pago. Se obtiene al crear un link con `/api/v2/links-pago/crear_link`
`mountSelector`	string	Sí	Selector HTML del elemento donde se renderizará el checkout. Puede ser cualquier elemento de tu página
`onPaymentSuccess`	función	Sí	Se ejecuta cuando el pago es aprobado. Recibe `redirectUrl` con la URL de confirmación y `data` con información del pago
`onPaymentReject`	función	Sí	Se ejecuta cuando el pago es rechazado. Recibe el objeto `error` con el detalle del rechazo
`onError`	función	Sí	Se ejecuta cuando ocurre un error en el proceso. Recibe el objeto `error` con el detalle del problema

Posibles respuestas

El componente dispara tres eventos según el resultado del pago. Tu aplicación decide qué hacer con cada uno:

Pago fue aprobado `onPaymentSuccess`

Recibes redirectUrl para enviar al usuario a la pantalla de confirmación y data con información básica de la transacción como los últimos dígitos de la tarjeta.

El pago fue rechazado `onPaymentReject`

Por ejemplo por fondos insuficientes o datos incorrectos. Recibes el detalle del rechazo en el objeto error.

Error `onError`

Ocurrió un error en el proceso que no está relacionado con el pago en sí, por ejemplo, un problema de conexión. Recibes el detalle en el objeto error.

mountSelector acepta cualquier selector CSS válido. En el ejemplo se usa #checkout pero puedes apuntar a cualquier elemento de tu página donde quieras que aparezca el formulario de pago.

Puedes usar cualquier elemento o evento para disparar el proceso de pago — no tiene que ser un botón. En el ejemplo se usa checkoutButton pero puedes adaptarlo a la lógica de tu aplicación.

Personalización visual

Puedes personalizar los colores del checkout para que se adapten a la identidad de tu marca. Los estilos se configuran al crear el link de pago, y cualquier valor definido en crear_link se aplicará automáticamente al componente.

Variables de color disponibles

Variable	Descripción
`accentColor`	Color principal del checkout. Se usa en métodos de pago seleccionados y elementos destacados
`surfaceColor`	Color de fondo del panel derecho, el área visible en mobile y en la parte principal del checkout en escritorio
`surfaceAltColor`	Color de fondo del panel izquierdo en escritorio. No aparece en mobile
`backgroundColor`	Color de fondo secundario usado en algunos componentes
`topColor`	Color de los elementos que aparecen sobre el contenido principal
`foregroundColor`	Color del texto en el panel derecho
`foregroundAltColor`	Color del texto en el panel izquierdo
`mutedColor`	Color de texto con menor énfasi, textos secundarios y placeholders
`buttonBackground`	Color de fondo del botón principal de pago
`buttonText`	Color del texto del botón principal de pago
`businessFont`	Tipografía usada en el checkout
`contentFont`	Tipografía usada en el contenido y formularios

Si no envías los colores de texto (foregroundColor, foregroundAltColor), el sistema los calcula automáticamente en base al color de fondo para garantizar contraste suficiente.

La personalización directa desde el componente vía la propiedad theme en create está próximamente disponible. Por el momento la configuración visual se realiza desde el link de pago o desde el panel de administración.

COMIENZA AQUÍ

INTEGRACIONES FRONTEND

INTEGRACIONES BACKEND V2

CASOS DE USO

El proceso tiene 3 pasos

Obtener el hash de la transacción

Montar el componente

1. Importar la librería

2. Inicializar el componente

Propiedades de `create`

Posibles respuestas

Pago fue aprobado `onPaymentSuccess`

El pago fue rechazado `onPaymentReject`

Error `onError`

Personalización visual

Variables de color disponibles

​El proceso tiene 3 pasos

​Obtener el hash de la transacción

​Montar el componente

​1. Importar la librería

​2. Inicializar el componente

​Propiedades de create

​Posibles respuestas

​Pago fue aprobado onPaymentSuccess

​El pago fue rechazado onPaymentReject

​Error onError

​Personalización visual

​Variables de color disponibles

El proceso tiene 3 pasos

Obtener el hash de la transacción

Montar el componente

1. Importar la librería

2. Inicializar el componente

Propiedades de `create`

Posibles respuestas

Pago fue aprobado `onPaymentSuccess`

El pago fue rechazado `onPaymentReject`

Error `onError`

Personalización visual

Variables de color disponibles