Referencia del Checkout Component

Esta página documenta toda la interfaz pública del Checkout Component: los métodos para inicializarlo, los parámetros de config, cada uno de los callbacks y la forma de los objetos que recibes. Para el paso a paso de integración ve a Pagos con Checkout Component.

📘

Versionado

El contrato (callbacks y objetos) avanza con la versión del Component, no con la versión de la API REST. Los campos se agregan de forma aditiva entre versiones. Esta referencia corresponde a la línea 4.x del Component.

Cómo se carga

<script crossorigin src="https://pay.conekta.com/v1.0/js/conekta-checkout.min.js"></script>

pay.conekta.com/v1.0/… es un punto de entrada estable: carga la build vigente del Component.

Métodos

Ambos reciben el mismo objeto con config y callbacks; options es opcional.

Checkout embebido — Integration (el flujo principal): monta el formulario de pago y procesa la orden.

window.ConektaCheckoutComponents.Integration({
  config: {
    publicKey: '{{yourKey}}',
    checkoutRequestId: '{{checkoutRequestId}}', // el checkout.id que creaste en tu servidor
    targetIFrame: 'example',
    locale: 'es',
  },
  callbacks: {
    onFinalizePayment: function (order) {
      // No es confirmación de pago: confírmalo en tu servidor (ver onFinalizePayment).
      console.log('Orden:', order.id);
    },
    onErrorPayment: function (error) {
      console.error('Error de pago:', error);
    },
  },
  options: {
    backgroundMode: 'lightMode', // lightMode o darkMode
    inputType: 'minimalMode',    // minimalMode o flatMode
  },
});

Solo tokenizador — Card: genera el token de una tarjeta. No crea una orden, por lo que no usa checkoutRequestId.

window.ConektaCheckoutComponents.Card({
  config: {
    publicKey: '{{yourKey}}',
    targetIFrame: 'example',
    locale: 'es',
  },
  callbacks: {
    onCreateTokenSucceeded: function (token) {
      // Envía el token a tu servidor para crear el cargo.
      console.log('Token:', token);
    },
    onCreateTokenError: function (error) {
      console.error('Error al tokenizar:', error);
    },
  },
});

Configuración (config)

Callbacks

Se pasan dentro del objeto callbacks. Todos son opcionales.

onGetInfoSuccess

Se dispara cuando el Component terminó de cargar.
(perf: { initLoadTime: number }) => void — initLoadTime es el tiempo de carga en ms.

onFinalizePayment

Se dispara cuando el pago se procesó correctamente. Recibe el objeto OrderDTO (ver abajo).
(order: OrderDTO) => void

⚠️

El callback no es una confirmación de pago. Confírmalo desde tu servidor: por el webhook order.paid, o consultando el estado de la orden y sus cargos vía API (Obtener una orden).

onErrorPayment

Se dispara cuando ocurrió un error durante el pago. Recibe un string (no un objeto).
(error: string) => void

onChargeFailed

Se dispara cuando falla el cargo. Recibe un objeto con el detalle del error.
(error: { code?: string; message: string }) => void

onCreateTokenSucceeded

(Flujo de tokenizador) Se dispara cuando se creó el token de tarjeta.
(token: string) => void

onCreateTokenError

(Flujo de tokenizador) Se dispara cuando falló la creación del token.
(error: string) => void

onFormError

Se dispara ante un error de validación del formulario.
(error: any) => void

onUpdateSubmitTrigger

Entrega la función de submit cuando usas useExternalSubmit: true. Guárdala e invócala desde tu propio botón "Pagar". Ver Submit externo para el flujo completo.
(submit: (args: any) => void) => void

onPayByBankWaitingPay

Se dispara en el estado de espera de Pago Directo (pay by bank).
(data: { provider: string; redirectUrl?: string; deepLink?: string; reference?: string }) => void

onEventListener

Flujo genérico de eventos del Component.
(payload: { name: string; value: any }) => void

preRedirect

Intercepta una redirección antes de que ocurra; resuelve false para cancelarla.
(urlRedirect: string) => Promise<boolean>

Submit externo

Por defecto el Component muestra su propio botón "Pagar". Para dispararlo desde un botón de tu interfaz:

1. Pasa useExternalSubmit: true en config; esto oculta el botón integrado.
2. Implementa el callback onUpdateSubmitTrigger: el Component te entrega una función submit cuando el checkout está listo para pagarse.
3. Guarda esa función e invócala desde el click de tu propio botón.

Agrega tu botón en tu HTML (vive en tu página, fuera del iframe del Component):

<button id="mi-boton-pagar">Pagar</button>

Luego inicializa el Component y conéctalo a ese botón:

// Placeholder hasta que el Component entregue la función real:
// si alguien hace click antes de tiempo, avisa en consola en vez de fallar.
let triggerSubmit = function () {
  console.warn('La función de submit aún no está disponible.');
};

window.ConektaCheckoutComponents.Integration({
  config: {
    publicKey: '{{yourKey}}',
    checkoutRequestId: '{{checkoutRequestId}}',
    targetIFrame: 'example',
    locale: 'es',
    useExternalSubmit: true, // oculta el botón integrado del Component
  },
  callbacks: {
    onUpdateSubmitTrigger: function (submit) {
      triggerSubmit = submit; // guarda la función de submit real
    },
    onFinalizePayment: function (order) {
      console.log('Orden:', order.id);
    },
  },
});

// '#mi-boton-pagar' es el botón que TÚ agregas a tu HTML; usa el selector del tuyo.
document.querySelector('#mi-boton-pagar').addEventListener('click', function () {
  triggerSubmit();
});

📘

onUpdateSubmitTrigger solo se invoca cuando useExternalSubmit es true y el checkout está listo para pagarse. Asegúrate de haber recibido la función submit antes de invocarla desde tu botón.

Objetos

OrderDTO — payload de onFinalizePayment

📘

Este objeto lo emite el Component y es específico de este flujo: no es el objeto order de la API REST (ese usa payment_status y una lista paginada de charges). Usa nombres en camelCase y trae tanto charge como charges.

Charge — elemento de charge / charges

Estados de cargo (status)