Card

V1

Integración

Agregar el script de checkout de Koin.

Producción: https://payments.koin.com.br/checkout/sdk/v1/methods.js
Sandbox: https://portal-dev.koin.com.br/checkout/sdk/v1/methods.js

API

Luego de agregar el script de checkout de Koin a tu página tendrás disponible dentro de window un objeto llamado KoinPayments.
Crear una instancia de la clase order para el método de pago CARD de la siguiente manera (se espera un string con el orderId generado en Koin):

// CARD - Initialization method
// Initialize CARD by Order
const card = await window.KoinPayments.order(orderId);

Una vez hecho esto, tendremos un objeto creado con los siguientes métodos:
1. initialize(afterInitializedCallback, options?): El método afterInitializedCallback se va a ejecutar solo cuando se haya podido inicializar el SDK de Card con éxito. Caso contrario se puede recibir el error utilizando onError. Opcionalmente podés pasar options: { language?: 'es' | 'en' | 'pt' } para forzar el idioma del checkout.
2. mount(containerCssSelector, hidePaymentButton?, hidePaymentSummary?): Monta el checkout de tarjeta en el contenedor indicado. Los errores relacionados a esta función se devuelven en el onError. Parámetros:
  - containerCssSelector: Selector CSS que apunte a un <div> donde se va a colocar el checkout de Koin.
  - hidePaymentButton (opcional): Si es true, oculta el botón de pago dentro del checkout.
  - hidePaymentSummary (opcional): Si es true, oculta el resumen del pago dentro del checkout.
3. submit(): Envía programáticamente el formulario de pago dentro del iframe (equivalente a que el usuario haga clic en el botón de confirmar). Debe llamarse después de mount().
4. onError({code, origin, message}): Manejo de errores de Koin. Siempre siguen el mismo formato.
5. onEvent(code, payload): Eventos para comunicar el estado del proceso. El payload es opcional (p. ej. para INSTALLMENT_SELECTED puede incluir datos de cuotas).
6. onFinish(data): Callback que se ejecuta cuando la orden está finalizada o su estado se actualizó (por ejemplo ya cobrada, cancelada o expirada).
7. destroy(): Elimina la instancia existente del SDK de Card si hay una.

Eventos

Code	Description	Origen
CONFIGURATION_SET	Ocurre cuando la configuración del SDK fue aplicada correctamente.	Koin
MOUNT_STARTED	Ocurre cuando se inicia el montaje del checkout.	Koin
CHECKOUT_LOADED	Ocurre cuando el iframe del checkout terminó de cargar.	Koin
OPENED	Ocurre cuando la orden está abierta.	Koin
AUTHORIZED	Ocurre cuando el pago fue autorizado.	Koin
COLLECTED	Ocurre cuando el pago fue cobrado.	Koin
VOIDED	Ocurre cuando la autorización fue anulada.	Koin
FAILED	Ocurre cuando el pago falló.	Koin
CANCELLED	Ocurre cuando el usuario canceló el flujo.	Koin
INSTALLMENT_SELECTED	Ocurre cuando el usuario seleccionó un plan de cuotas (el payload puede incluir datos de la cuota).	Koin

Errores

Code	Description	Origen
INIT_MISSING_WISH_ID	Ocurre cuando la consulta interna por order_id que fue usado en KoinPayments.order() no retorna ningún wish_id.	Koin
INIT_MISSING_ORDER_ID	Ocurre cuando el order_id que fue usado en KoinPayments.order() es undefined o null.	Koin
MOUNT_ERROR	Ocurre cuando no se pudo encontrar el contenedor especificado para montar el checkout o ocurrió un error interno al crear el mismo.	Koin
INITIALIZE_ERROR	Ocurre cuando la configuración no es válida.	Koin
CONFIGURATION_ERROR	Ocurre cuando existe un error de configuración del listener de comunicación.	Koin

Ejemplo

1 - Crear una instancia de checkout

Solo deberán pasar el orderId generado en Koin.

const card = await window.KoinPayments.order(orderId);

2 - Agregar listeners

Sólo se puede usar una sola vez cada método, onError, onEvent y onFinish.

card.onError((error) => {
  console.log("Error from callback: ", error.code, error.message, error.origin);
});

card.onEvent((event, payload) => {
  console.log("Event from callback: ", event, payload);
  switch (event) {
    case "OPENED":
      break;
    case "AUTHORIZED":
      break;
    case "COLLECTED":
      break;
    case "INSTALLMENT_SELECTED":
      // payload puede contener datos de la cuota seleccionada
      break;
    default:
      break;
  }
});

card.onFinish((data) => {
  console.log("Order finished: ", data);
});

3 - Iniciar flujo y montar el checkout

El método initialize se puede usar la cantidad de veces que se necesite. El método mount se debe usar dentro del callback del initialize:

async function onClick() {
  card.initialize(() => {
    console.log("Initialized");
    // Montar checkout; opcionalmente ocultar botón o resumen
    card.mount("#checkout-container");
    // card.mount("#checkout-container", true, false); // ocultar botón de pago
  });
}

4 - Enviar el pago por código (submit)

Si usás hidePaymentButton: true, podés llamar a submit() cuando el usuario confirme desde tu propia UI:

card.initialize(() => {
  card.mount("#checkout-container", true, false);
});

// Más tarde, cuando el usuario confirme (ej. tu propio botón):
document.querySelector("#my-confirm-button").addEventListener("click", () => {
  card.submit();
});

5 - Código completo

const card = await window.KoinPayments.order(orderId);

card.onError((error) => {
  console.log("Error: ", error.code, error.message, error.origin);
});

card.onEvent((event, payload) => {
  console.log("Event: ", event, payload);
});

card.onFinish((data) => {
  console.log("Order finished: ", data);
});

async function onClick() {
  card.initialize(() => {
    console.log("Initialized");
    card.mount("#checkout-container");
  });
}