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 }. status es Collected, Cancelled o Failed (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 Itaú Pay si hay una.

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

Eventos

Errores

Estados de onFinish

data.status es el estado de la orden en PascalCase. No es el código de onEvent. PUBLISHED no llama 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.

¿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.

//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;
  }
});

itauPay.onFinish((data) => {
  console.log("Finish from callback: ", data.status, data.message);
  switch (data.status) {
    case "Collected":
      //Ocurre cuando el pago fue cobrado
      break;
    case "Cancelled":
      //Ocurre cuando el pago fue cancelado 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;
  }
});

itauPay.onFinish((data) => {
  console.log("Finish from callback: ", data.status, data.message);
  switch (data.status) {
    case "Collected":
      //Ocurre cuando el pago fue cobrado
      break;
    case "Cancelled":
      //Ocurre cuando el pago fue cancelado 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,
    }
  );
}