Apple Pay

⚠️
Content Security Policy (CSP)
Para que esta wallet funcione correctamente en tu sitio, debés incluir en tu Content Security Policy los dominios que devuelve el endpoint de Koin. Si no los agregás, el botón o el checkout pueden no cargar.

V2

Requisitos

Previo a poder utilizar la SDK en ambiente productivo, es necesario realizar el registro pertinente en Apple del dominio del merchant.

Se deja a continuación un ejemplo con el flujo de registro:

Cliente informa que la SDK será utilizada bajo el dominio https://www.cliente.com.br
KOIN registra dicho dominio en Apple para el merchant
KOIN comparte el archivo de validación (apple-developer-merchantid-domain-association.txt) con el cliente (archivo unico por merchant).
El cliente deberá disponibilizar dicho archivo en https://www.cliente.com.br/.well-known/apple-developer-merchantid-domain-association.txt
Una vez el archivo se encuentre disponible en esa URL, KOIN dispara la validación en Apple para dar por finalizado el registro del merchant.

Integración

Agregar el script de wallets 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 wallets de Koin a tu página tendrás disponible dentro de window un objeto llamado KoinPayments.
Crear una instancia de la clase wallet u order para el método de pago APPLE_PAY de la siguiente manera:

//ApplePay initialization methods
//Initialize APPLE_PAY by Wallet
const applepay = await window.KoinPayments.wallet(initData);

//Initialize APPLE_PAY by Order
const applepay = await window.KoinPayments.order(orderId);

El objeto initData, para el método de inicialización vía Wallet, va a ser lo que devuelve payments en la llamada al InitWallet y debería tener la siguiente estructura:

{
  "provider": {
    "code": "APPLE_PAY",
    "js": "https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js",
    "jwt": "eyJhbGciDiJIUzIlNiIsInR5cCI6IkpXVCJ9.eyJjb3V..."
  },
  "dynamic_payment_key": "11c73b07-cc98-4ee8-bb57-a662a7b5829e"
}

En el caso del método de inicialización vía Orden, se espera un string con el orderId generado en Koin.

Una vez hecho esto, sin importar el método de inicialización, tendremos un objeto creado con los siguientes métodos:
initialize(afterInitializedCallback, options?): El método afterInitializedCallback se va a ejecutar solo cuando se haya podido inicializar el sdk de Apple 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 botón.
mount(buttonCssSelector): Los errores relacionados a esta función también se devuelven en el onError. Esta función recibe un parámetro, buttonCssSelector, el cual es selector CSS que apunte a un <div> dónde se va a colocar el botón de Apple Pay.

onError({code, origin, message}): Manejo de errores de ApplePay o Koin. Siempre siguen el mismo formato.
onSuccess({data}): Caso exitoso. Devuelve wallet_code, el koin_token (o datos equivalentes) e información de la tarjeta en un mismo objeto.

//onSuccess
{
    "wallet_code": "APPLE_PAY",
    "card": {
        "type": "CREDIT",
        "brand": {
            "name": "Visa",
            "code": "VI"
        },
        "instrument_token": "5e8fa408-7539-4402-85f3-43c6e9635177"
    }
}

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ó (solo aplica cuando se usa inicialización por order).
destroy(): Elimina la instancia existente del SDK de Apple Pay si hay una.

Eventos

Code	Description	Contexto
SCRIPT_LOADED	Ocurre cuando el script de ApplePay es cargado.	Wallet Order
USER_AGENT_DETECTED	Ocurre al montar el botón, con datos de debug (navegador, dispositivo, versión iOS, etc.). Payload opcional.	Wallet Order
BUTTON_LOADED	Ocurre cuando el botón de ApplePay aparece en pantalla.	Wallet Order
SESSION_STARTED	Ocurre cuando el usuario hace clic en el botón de “Pagar con Apple Pay”.	Wallet Order
SESSION_COMPLETED	Ocurre cuando la sesión de Apple Pay fue iniciada correctamente.	Wallet Order
SESSION_CANCELLED	Ocurre cuando el usuario, en cualquier momento, da por finalizada la experiencia de pagar con Apple Pay.	Wallet Order
SESSION_FAILED	Ocurre cuando la sesión falla internamente en la etapa de inicialización.	Wallet Order
MERCHANT_VALIDATION_STARTED	Ocurre luego de que la sesión de Apple Pay fue iniciada correctamente.	Wallet Order
MERCHANT_VALIDATION_COMPLETED	Ocurre cuando la validación del merchant es correcta y la hoja de pago es presentada al usuario.	Wallet Order
MERCHANT_VALIDATION_FAILED	Ocurre cuando la validación del merchant falla y esto hace que la hoja de pago se cierre automáticamente.	Wallet Order
PAYMENT_AUTHORIZATION_STARTED	Ocurre luego de que el usuario haya indicado que quiere confirmar la compra y realizado con éxito las validaciones (biometría, etc)	Wallet Order
PAYMENT_AUTHORIZATION_COMPLETED	Ocurre cuando la confirmación de pago se realiza con éxito.	Wallet Order
PAYMENT_AUTHORIZATION_FAILED	Ocurre cuando la confirmación de pago falla internamente (puede ser por error de Apple o Koin)	Wallet Order
UPDATE_ORDER_STATUS_FAILED	Ocurre cuando la captura de la autorización falló.	Order
UPDATE_ORDER_STATUS_COMPLETED	Ocurre cuando la captura de la autorización se realizó con éxito.	Order

Errores

Code	Description	Origen
NOT_SUPPORTED_BROWSER	Ocurre cuando Apple Pay no está disponible en ese explorador.	Apple
NOT_SUPPORTED_DEVICE	Ocurre cuando Apple Pay no es soportado en ese dispositivo.	Apple
NOT_SUPPORTED_IOS_VERSION	Ocurre cuando el dispositivo es iPhone/iPad con iOS anterior a 16.2.	Apple
VALIDATE_MERCHANT_SESSION_ERROR	Ocurre cuando Apple Pay detecta que la validación del merchant falló (cerrando la hoja de pago sin dar la posibilidad a pagar)	Apple
INIT_MISSING_DYNAMIC_PAYMENT_KEY	Ocurre cuando la dynamic payment key no existe y es requerida	Koin
INIT_MISSING_ORDER_ID	Ocurre cuando el order id no existe y es requerido	Koin
INIT_MISSING_JS	Ocurre cuando la url del JS no existe	Koin
INIT_MISSING_JWT	Ocurre cuando el JWT con los datos de la orden no existe	Koin
PAYMENT_REQUEST_NOT_AVAILABLE	Ocurre cuando el JWT no contiene el objeto payment request para crear la sesión de Apple Pay	Koin
KOIN_TOKEN_ERROR	Ocurre cuando no es posible obtener el koin_token luego de finalizada la experiencia apple pay y confirmado el pago por el usuario	Koin
CONFIGURATION_ERROR	Ocurre cuando hay un error interno obteniendo y/o configurando la wallet para su posterior uso.	Koin
PAYMENT_AUTHORIZED_ERROR	Ocurre cuando hay un error interno al momento de obtener y procesar el payment data de Apple Pay	Koin
UPDATE_ORDER_STATUS_ERROR	Ocurre cuando hay un error interno al momento de capturar el pago, sólo aplica para Orden.	Koin

Ejemplo

1 - Crear una instancia de la wallet

Para el caso de wallet, el objeto initData vendrá desde Payments. Tendrás que pasarlo como único parámetro sin hacerle ninguna modificación, sin embargo, para el caso de order, solo deberán especificar el orderId generado en Koin.

//ApplePay initialization methods
//Initialize APPLE_PAY by Wallet
const applepay = await window.KoinPayments.wallet(initData);

//Initialize APPLE_PAY by Order
const applepay = await window.KoinPayments.order(orderId);

2 - Agregar listeners

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

//Listeners
applepay.onSuccess((data) => {
  console.log("Koin Token + Card info: ", data);
});

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

applepay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "SCRIPT_LOADED":
      // Ocurre cuando el script de ApplePay es cargado.
      break;
    case "BUTTON_LOADED":
      // Ocurre cuando el botón de ApplePay aparece en pantalla.
      break;
    case "SESSION_STARTED":
      // Ocurre cuando el usuario hace clic en el botón de "Pagar con Apple Pay".
      break;
    case "SESSION_COMPLETED":
      // Ocurre cuando la sesión de Apple Pay fue iniciada correctamente.
      break;
    case "SESSION_CANCELLED":
      // Ocurre cuando el usuario, en cualquier momento, da por finalizada la experiencia de pagar con Apple Pay.
      break;
    case "SESSION_FAILED":
      // Ocurre cuando la sesión falla internamente en la etapa de inicialización.
      break;
    case "MERCHANT_VALIDATION_STARTED":
      // Ocurre luego de que la sesión de Apple Pay fue iniciada correctamente.
      break;
    case "MERCHANT_VALIDATION_COMPLETED":
      // Ocurre cuando la validación del merchant es correcta y la hoja de pago es presentada al usuario.
      break;
    case "MERCHANT_VALIDATION_FAILED":
      // Ocurre cuando la validación del merchant falla y esto hace que la hoja de pago se cierre automáticamente.
      break;
    case "PAYMENT_AUTHORIZATION_STARTED":
      // Ocurre luego de que el usuario haya indicado que quiere confirmar la compra y realizado con éxito las validaciones (biometría, etc)
      break;
    case "PAYMENT_AUTHORIZATION_COMPLETED":
      // Ocurre cuando la confirmación de pago se realiza con éxito.
      break;
    case "PAYMENT_AUTHORIZATION_FAILED":
      // Ocurre cuando la confirmación de pago falla internamente (puede ser por error de Apple o Koin)
      break;
    case "UPDATE_ORDER_STATUS_FAILED":
      // Ocurre cuando la captura de la autorización falló (solo aplica para order)
      break;
    case "UPDATE_ORDER_STATUS_COMPLETED":
      // Ocurre cuando la captura de la autorización se realizó con éxito (solo aplica para order)
      break;
  }
});

3 - Iniciar flujo y montar el botón de Apple Pay

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 and mount methods
const applepay = await window.KoinPayments.wallet(initData);
//const applepay = await window.KoinPayments.order(orderId);

async function onClick() {
  applepay.initialize(() => {
    console.log("Initialized");
    // #btn-container es la div donde se montará el botón de Pagar con Apple Pay.
    applepay.mount("#btn-container");
  });
}

4 - Código completo

//Example
const applepay = await window.KoinPayments.wallet(initData);
//const applepay = await window.KoinPayments.order(orderId);

applepay.onSuccess((data) => {
  console.log("Koin Token + Card info: ", data);
});

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

applepay.onEvent((event) => {
  console.log("Event from callback: ", event);
  switch (event) {
    case "SCRIPT_LOADED":
      // Ocurre cuando el script de ApplePay es cargado.
      break;
    case "BUTTON_LOADED":
      // Ocurre cuando el botón de ApplePay aparece en pantalla.
      break;
    case "SESSION_STARTED":
      // Ocurre cuando el usuario hace clic en el botón de "Pagar con Apple Pay".
      break;
    case "SESSION_COMPLETED":
      // Ocurre cuando la sesión de Apple Pay fue iniciada correctamente.
      break;
    case "SESSION_CANCELLED":
      // Ocurre cuando el usuario, en cualquier momento, da por finalizada la experiencia de pagar con Apple Pay.
      break;
    case "SESSION_FAILED":
      // Ocurre cuando la sesión falla internamente en la etapa de inicialización.
      break;
    case "MERCHANT_VALIDATION_STARTED":
      // Ocurre luego de que la sesión de Apple Pay fue iniciada correctamente.
      break;
    case "MERCHANT_VALIDATION_COMPLETED":
      // Ocurre cuando la validación del merchant es correcta y la hoja de pago es presentada al usuario.
      break;
    case "MERCHANT_VALIDATION_FAILED":
      // Ocurre cuando la validación del merchant falla y esto hace que la hoja de pago se cierre automáticamente.
      break;
    case "PAYMENT_AUTHORIZATION_STARTED":
      // Ocurre luego de que el usuario haya indicado que quiere confirmar la compra y realizado con éxito las validaciones (biometría, etc)
      break;
    case "PAYMENT_AUTHORIZATION_COMPLETED":
      // Ocurre cuando la confirmación de pago se realiza con éxito.
      break;
    case "PAYMENT_AUTHORIZATION_FAILED":
      // Ocurre cuando la confirmación de pago falla internamente (puede ser por error de Apple o Koin)
      break;
    case "UPDATE_ORDER_STATUS_FAILED":
      // Ocurre cuando la captura de la autorización falló (solo aplica para order)
      break;
    case "UPDATE_ORDER_STATUS_COMPLETED":
      // Ocurre cuando la captura de la autorización se realizó con éxito (solo aplica para order)
      break;
  }
});

async function onClick() {
  applepay.initialize(() => {
    console.log("Initialized");
    // #btn-container es la div donde se montará el botón de Pagar con Apple Pay.
    applepay.mount("#btn-container");
  });
}