MODO

Changelog

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

//MODO - Initialization method
//Initialize MODO by Order
const modo = 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 MODO con éxito. Caso contrario se puede recibir el error utilizando onError. Opcionalmente podés pasar options: { language?: 'es' | 'en' | 'pt'; title?: string; subtitle?: string; showQR?: boolean } para forzar el idioma del checkout, personalizar el título y subtítulo, y controlar la visibilidad del QR.
      • 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(divCssSelector): Los errores relacionados a esta función también se devuelven en el onError. Esta función recibe un parámetro, divCssSelector, el cual es selector CSS que apunte a un <div> dónde se va a colocar el checkout de Koin.

   

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

//MODO - Initialization method
//Initialize MODO by Order
const modo = 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.

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

modo.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
  }
});

modo.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):

//MODO - Init and mount methods
//Initialize MODO by Order
const modo = await window.KoinPayments.order(orderId);

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

4 - Código completo

//MODO - Example
const modo = await window.KoinPayments.order(orderId);

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

modo.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
  }
});

modo.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() {
  modo.initialize(
    () => {
      console.log("Initialized");
      //#checkout-container es la div donde se montará la experiencia de checkout
      modo.mount("#checkout-container");
    },
    {
      language: "es",
      title: "Pagá con MODO",
      subtitle: "Escaneá el QR",
      showQR: true,
    }
  );
}