Payment Method Selector

El Payment Method Selector es un componente embebido que muestra al usuario todos los medios de pago habilitados para el comercio y monta automáticamente el checkout del medio elegido, sin salir de la web de la tienda.

Esta documentación cubre únicamente la integración por canal SDK.

Changelog

V1.0.0

Integración

1. Crea una transacción de selección de medio de pago contra el backend de Koin.

2. La respuesta incluye un transaction_id (y un return_url por si prefieres redirigir al usuario al checkout hospedado de Koin).

3. Para la integración SDK, utiliza el transaction_id recibido.

4. Agrega 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 del Payment Method Selector de la siguiente manera (se espera el transaction_id que recibiste en la respuesta de la creación de la transacción):

const pms = await window.KoinPayments.transaction(transactionId);

Si falta transaction_id, el constructor lanza un UnifiedError con código INIT_MISSING_TRANSACTION_ID.

3. Una vez hecho esto, tendremos un objeto creado con los siguientes métodos:
   1. initialize(afterInitializedCallback, options?): El método afterInitializedCallback se ejecuta cuando el selector se inicializó correctamente. 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(containerTarget): Monta el selector en el contenedor indicado. Recibe un HTMLElement (no un selector CSS). Los errores relacionados a esta función se devuelven en el onError. Debe llamarse dentro del callback de initialize.
   3. onError({code, origin, message}): Manejo de errores de Koin. Siempre siguen el mismo formato.
   4. onEvent(code, payload): Eventos para comunicar el estado del proceso. El payload es opcional dependiendo del evento que se dispare.
   5. onSuccess(data): Callback que se ejecuta cuando el medio de pago activo reporta un éxito intermedio. El formato de data depende del medio elegido.
   6. onFinish(data): Callback que se ejecuta cuando el pago alcanza un estado terminal. El campo data.status puede ser uno de los siguientes valores:

7. destroy(): Elimina la instancia activa y vacía el contenedor.

Medios disponibles (según configuración del comercio):

• APPLE_PAY
• ASTRO_PAY
• CARD
• CLICK_TO_PAY
• DEBIN
• MODO
• PAYPAL
• PIX
• SAFETY_PAY

Si tu sitio define una Content Security Policy (CSP), revisá Content Security Policy.

Eventos

Errores

También pueden llegar errores propagados desde el medio de pago embebido (origin distinto de KOIN, p. ej. ASTRO_PAY, PAYPAL). No los listamos aquí. Recomendamos manejar todos los errores de la misma forma: son irrecuperables — informá al usuario y ofrecé reintentar creando una nueva transacción.

Ejemplo

1 - Crear una instancia de checkout

Solo deberán pasar el transactionId generado en Koin.

const pms = await window.KoinPayments.transaction(transactionId);

2 - Agregar listeners

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

pms.onFinish((data) => {
  console.log("Finish from callback: ", data);

  switch (data.status) {
    case "Collected":
    case "Authorized":
      // Ocurre cuando el pago fue exitoso
      break;
    case "Cancelled":
      // Ocurre cuando el pago fue cancelado por el usuario o expiró
      break;
    case "Failed":
      // Ocurre cuando un error interno y el caso es irrecuperable
      break;
    case "Voided":
      // Ocurre cuando la autorización fue anulada
      break;
  }
});

3 - Iniciar flujo y montar el checkout de Koin

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

const container = document.getElementById("checkout-container");

pms.initialize(
  () => {
    console.log("Initialized");
    pms.mount(container);
  },
  { language: "es" },
);

4 - Código completo

async function mountPaymentMethodSelector(transactionId) {
  try {
    const pms = await window.KoinPayments.transaction(transactionId);

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

    pms.onFinish((data) => {
      console.log("Finish from callback: ", data);

      switch (data.status) {
        case "Collected":
        case "Authorized":
          break;
        case "Cancelled":
        case "Failed":
        case "Voided":
          break;
      }
    });

    const container = document.getElementById("checkout-container");

    pms.initialize(
      () => {
        console.log("Initialized");
        pms.mount(container);
      },
      { language: "es" },
    );
  } catch (error) {
    console.error("Failed to create Payment Method Selector:", error);
  }
}

Playground