Safety Pay

V1

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

Luego de agregar el script de checkout de Koin a tu página tendrás disponible dentro de window un objeto llamado KoinPayments.
Crear una instancia de la clase order para el método de pago SafetyPay de la siguiente manera (se espera un string con el orderId generado en Koin):

//Initialize SafetyPay by Order
const safetypay = await window.KoinPayments.order(orderId);

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 SafetyPay 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(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.
onError({code, origin, message}): Manejo de errores de Koin. Siempre siguen el mismo formato.
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.
onFinish(data): Callback que se ejecuta cuando la orden está finalizada o su estado se actualizó (por ejemplo ya cobrada, cancelada o expirada).
destroy(): Elimina la instancia existente del SDK de SafetyPay si hay una.
1. Vamos a dejarle decidir a la tienda en qué momento desmontar el iframe.

Eventos

Code	Description	Origen
CONFIGURATION_SET	Ocurre cuando la configuración del SDK fue aplicada correctamente.	Koin
MOUNT_STARTED	Ocurre cuando se inicia el montaje del checkout.	Koin
CHECKOUT_LOADED	Ocurre cuando el iframe del checkout terminó de cargar.	Koin
PUBLISHED	Ocurre cuando la deuda fue publicada	Koin
COLLECT	Ocurre cuando la deuda fue cobrada	Koin
REJECTED_OR_EXPIRED	Ocurre cuando la deuda fue cancelada por el usuario o expiró	Koin
FAILED	Cuando ocurre un error interno y el caso es irrecuperable	Koin
WALLET_DESTROYED	Ocurre cuando se llamó a destroy() y la instancia fue eliminada.	Koin

Errores

Code	Description	Origen
INIT_MISSING_WISH_ID	Ocurre cuando la consulta interna por order_id que fue usado en KoinPayments.order() no retorna ningún wish_id.	Koin
INIT_MISSING_ORDER_ID	Ocurre cuando el order_id que fue usado en KoinPayments.order() es undefined o null.	Koin
MOUNT_ERROR	Ocurre cuando no se pudo encontrar el contenedor especificado para montar el checkout o ocurrió un error interno al crear el mismo.	Koin
INITIALIZE_ERROR	Ocurre cuando la configuración no es válida.	Koin
CONFIGURATION_ERROR	Ocurre cuando existe un error de configuración del listener de comunicación.	Koin

Ejemplo

1 - Crear una instancia de checkout

Solo deberán pasar el orderId generado en Koin.

//Initialize SafetyPay by Order
const safetypay = 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.

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

safetypay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
    case "COLLECT":
      //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":
      //Ocurre cuando 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):

//Initialize SafetyPay by Order
const safetypay = await window.KoinPayments.order(orderId);

async function onClick() {
  safetypay.initialize(() => {
    console.log("Initialized");
    //#checkout-container es la div donde se montará la experiencia de checkout
    safetypay.mount("#checkout-container");
  });
}

4 - Código completo

//Initialize SafetyPay by Order
const safetypay = await window.KoinPayments.order(orderId);

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

safetypay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "PUBLISHED":
      //Ocurre cuando la deuda fue publicada
      break;
    case "COLLECT":
      //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":
      //Ocurre cuando un error interno y el caso es irrecuperable
      break;
  }
});

async function onClick() {
  safetypay.initialize(() => {
    console.log("Initialized");
    //#checkout-container es la div donde se montará la experiencia de checkout
    safetypay.mount("#checkout-container");
  });
}