Card

Changelog

V1.3.0

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

1. Luego de agregar el script de checkout de Koin a tu página tendrás disponible dentro de window un objeto llamado KoinPayments.
2. 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);

3. 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(): Promise<SubmitResult>: Envía programáticamente el formulario de pago dentro del iframe (equivalente a que el usuario haga clic en el botón de confirmar) y devuelve el resultado del envío. 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). El data contiene { status, message }. status es Authorized, Collected, Cancelled, Failed o Voided (PascalCase; no es el código de onEvent). Si la orden ya estaba terminada al llamar a initialize, el mensaje es Order already finished. Si el iframe informa un estado final, el mensaje es Order status updated.
   7. destroy(): Elimina la instancia existente del SDK de Card si hay una.

Resultado de submit

El método submit() siempre resuelve una Promise con el siguiente contrato:

type SubmitResult = {
  submitted: boolean;
  id: string;
};

• id: Es el mismo orderId utilizado para crear la instancia mediante KoinPayments.order(orderId).
• submitted: true: La tarjeta se tokenizó correctamente y la solicitud HTTP de compra fue aceptada. En este punto el comercio puede cerrar el SDK.
• submitted: false: El envío no pudo completarse. El comercio debe mantener el SDK abierto para que el usuario pueda corregir el formulario o volver a intentarlo.

submitted: true no indica el estado final de la transacción. El resultado definitivo, por ejemplo Collected o Failed, se informa mediante onFinish.

Los errores de los campos no forman parte de SubmitResult: se muestran en la interfaz del SDK y se informan mediante el evento FORM_VALIDATION.

submit() resuelve con submitted: false cuando el formulario no es válido, no hay una cuota seleccionada, el checkout todavía no está listo, falla la tokenización o la creación de la compra, no se recibe respuesta en 30 segundos, o ya existe otro submit() pendiente. Una llamada concurrente no inicia una compra duplicada. Si falla la tokenización, el mismo fallo llega por onError con CARD_NOT_SUPPORTED, BIN_INFORMATION_MISSING o UNKNOWN.

Eventos

Errores

Estados de onFinish

data.status es el estado de la orden en PascalCase. No es el código de onEvent. OPENED, INSTALLMENT_SELECTED y FORM_VALIDATION no llaman a onFinish.

FAQ

¿onFinish se dispara siempre con la orden en un estado final?

Sí. onFinish se dispara solo con un estado final de la tabla de arriba. No se dispara con eventos intermedios, una revisión de antifraude, una autenticación 3DS ni un pago pendiente.

Authorized es un estado final. Una orden que quedó Authorized no vuelve a Cancelled ni a Voided.

¿Qué pasa si hay timeout, error de red, o el usuario cierra la pestaña?

Si el usuario cierra la pestaña, el SDK no lo informa por ningún evento. Timeout y error de red tampoco disparan onFinish. En esos casos el estado de la orden se toma de la notificación por webhook y del GET /v1/payment/orders/{id}. onError no es ese estado: aunque un fallo del SDK pueda llegar por ahí, no reemplaza a la notificación por webhook ni al GET.

Si la orden expira, onFinish sí se dispara, con status Cancelled.

¿El status de onFinish puede diferir del GET o del webhook?

No. El status de onFinish sale del mismo GET /v1/payment/orders/{id} y es un estado final. Consultar ese GET en ese momento devuelve la misma respuesta.

La fuente de verdad es siempre la notificación por webhook y ese GET. No recomendamos, bajo ningún término, reemplazar la notificación por webhook o el GET Status por el onFinish del SDK.

Cuando se dispara onFinish, ¿el estado ya está en la API?

Sí. Como el status sale de ese mismo GET, no hay demora. El estado ya está reflejado en la API.

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 "INSTALLMENT_SELECTED":
      // payload puede contener datos de la cuota seleccionada
      break;
    case "FORM_VALIDATION":
      // payload contiene el resultado de la validación
      break;
    default:
      break;
  }
});

card.onFinish((data) => {
  console.log("Finish from callback: ", data.status, data.message);
  switch (data.status) {
    case "Authorized":
      // El pago fue autorizado
      break;
    case "Collected":
      // El pago fue cobrado
      break;
    case "Cancelled":
      // El usuario canceló el flujo
      break;
    case "Failed":
      // El pago falló
      break;
    case "Voided":
      // La autorización fue anulada
      break;
  }
});

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", async () => {
    const result = await card.submit();

    if (result.submitted) {
      console.log("Compra enviada para la orden:", result.id);
      card.destroy();
      return;
    }

    console.log("El SDK debe permanecer abierto para corregir o reintentar");
  });

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("Finish from callback: ", data.status, data.message);
  switch (data.status) {
    case "Authorized":
      // El pago fue autorizado
      break;
    case "Collected":
      // El pago fue cobrado
      break;
    case "Cancelled":
      // El usuario canceló el flujo
      break;
    case "Failed":
      // El pago falló
      break;
    case "Voided":
      // La autorización fue anulada
      break;
  }
});

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

document
  .querySelector("#my-confirm-button")
  .addEventListener("click", async () => {
    const { submitted, id } = await card.submit();
    console.log("Submit result: ", { submitted, id });

    if (submitted) {
      card.destroy();
    }
  });