PIX

Changelog

V1.0.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 PIX de la siguiente manera (se espera un string con el orderId generado en Koin):

// PIX - Initialization method
// Initialize PIX by Order
const pix = 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 PIX 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): Monta el checkout de PIX (con el QR y el código copy & paste) 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.

      A diferencia de Card, PIX no expone hidePaymentButton ni hidePaymentSummary: el resumen de pago en contexto SDK se oculta siempre y la confirmación la hace el usuario directamente desde su app bancaria escaneando el QR.

   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.

   5. 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 }.

   6. destroy(): Elimina la instancia existente del SDK de PIX si hay una.

Eventos

Errores

Ejemplo

1 - Crear una instancia de checkout

Solo deberán pasar el orderId generado en Koin.

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

2 - Agregar listeners

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

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

pix.onEvent((event, payload) => {
  console.log("Event from callback: ", event, payload);
  switch (event) {
    case "PUBLISHED":
      // El QR ya está visible y listo para ser escaneado
      break;
    case "COLLECTED":
      // El pago fue cobrado
      break;
    case "CANCELLED":
      // El usuario canceló o el QR fue cancelado
      break;
    case "FAILED":
      // El caso es irrecuperable
      break;
    default:
      break;
  }
});

pix.onFinish((data) => {
  console.log("Order finished: ", data); // { status, message }
});

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() {
  pix.initialize(() => {
    console.log("Initialized");
    // #checkout-container es la div donde se montará la experiencia de checkout
    pix.mount("#checkout-container");
  });
}

4 - Código completo

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

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

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

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

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