Itaú Pay

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 Itaú Pay de la siguiente manera (se espera un string con el orderId generado en Koin):

//Itaú Pay - Initialization method
//Initialize Itaú Pay by Order
const itauPay = await window.KoinPayments.order(orderId);

3. Una vez hecho esto, sin importar el método de inicialización, 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 Itaú Pay con éxito. Caso contrario se puede recibir el error utilizando onError. Opcionalmente podés pasar options:

      ts

      {
        language?: 'es' | 'en' | 'pt';
        flow?: 'MOBILE' | 'WEB';
        title?: string;
        subtitle?: string;
        showQR?: boolean;
      }

      • language: fuerza el idioma del checkout.
      • flow: define el flujo del checkout. Si no lo pasás, el SDK no envía el parámetro y el checkout lo resuelve (por defecto WEB).
      • title y subtitle: personalizan el título y el subtítulo que se muestran en el checkout. Se recortan los espacios; un string vacío no se envía.
      • showQR: con true, el SDK mobile muestra el QR. Si se omite o es false, en mobile solo se muestra la acción de deeplink. En desktop el QR se muestra siempre.

   2. mount(containerTarget): Los errores relacionados a esta función también se devuelven en el onError. Recibe un containerTarget, que puede ser un selector CSS que apunte a un <div> o un HTMLElement, dónde se va a colocar el checkout de Koin. Al llamarlo se dispara MOUNT_STARTED. Cuando el iframe termina de cargar se dispara CHECKOUT_LOADED.

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 cuando sea posible y mantener al tanto al consumidor de nuestro script. El payload es opcional dependiendo del evento que se dispare.

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 }. 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 Itaú Pay si hay una.

   1. Vamos a dejarle decidir a la tienda en qué momento desmontar el iframe.

Eventos

Errores

Ejemplo

1 - Crear una instancia de checkout

Solo deberán pasar el orderId generado en Koin.

//Itaú Pay - Initialization method
//Initialize Itaú Pay by Order
const itauPay = await window.KoinPayments.order(orderId);

2 - Agregar listeners

Sólo se puede usar una sola vez cada método, onError, onEvent y onFinish.
Podés ver los eventos disponibles y los errores posibles en la documentación de Wallets y checkout SDK.

//Itaú Pay - Listeners
itauPay.onError((error) => {
  console.log("Error from callback: ", error.code, error.message, error.origin);
});

itauPay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
    case "COLLECTED":
      //Ocurre cuando la deuda fue cobrada
      break;
    case "REJECTED_OR_EXPIRED":
      //Ocurre cuando la deuda fue cancelada por el usuario o expiró
      break;
    case "FAILED":
      //Cuando ocurre un error interno y el caso es irrecuperable
      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 de la siguiente manera (y siempre dentro del callback del initialize):

//Itaú Pay - Init and mount methods
//Initialize Itaú Pay by Order
const itauPay = await window.KoinPayments.order(orderId);

async function onClick() {
  itauPay.initialize(
    () => {
      console.log("Initialized");
      //#checkout-container es la div donde se montará la experiencia de checkout
      itauPay.mount("#checkout-container");
    },
    {
      language: "es",
      flow: "WEB",
      title: "Pagá con Itaú Pay",
      subtitle: "Escaneá el QR",
      showQR: true,
    }
  );
}

4 - Código completo

//Itaú Pay - Example
const itauPay = await window.KoinPayments.order(orderId);

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

itauPay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
    case "COLLECTED":
      //Ocurre cuando la deuda fue cobrada
      break;
    case "REJECTED_OR_EXPIRED":
      //Ocurre cuando la deuda fue cancelada por el usuario o expiró
      break;
    case "FAILED":
      //Cuando ocurre un error interno y el caso es irrecuperable
      break;
  }
});

async function onClick() {
  itauPay.initialize(
    () => {
      console.log("Initialized");
      //#checkout-container es la div donde se montará la experiencia de checkout
      itauPay.mount("#checkout-container");
    },
    {
      language: "es",
      flow: "WEB",
      title: "Pagá con Itaú Pay",
      subtitle: "Escaneá el QR",
      showQR: true,
    }
  );
}