Zenki
Zenki Principal Habilitar modo claro/oscuro Habilitar modo claro/oscuro Habilitar modo claro/oscuro Regresar a la página principal
  1. Documentación Zenki
  2. /
  3. Zenkipay
  4. /
  5. Proceso de Integración
  6. /
  7. Mecanismos de Integración
  8. /
  9. Integración con nuestro script de Javascript

Integración con nuestro script de Javascript

Al darle click al botón Continuar, se mostrará un snippet de código que debes copiar y/o adaptar en tu sitio web, dicho snippet trae un ejemplo de como puedes integrarlo.

script

Para integrar el script de Zenkipay, necesitas agregarlo a tu sitio, recomendamos agregarle tu zenkipayKey como query param, el cual puedes extraerlo del snippet; en caso contrario también puedes pasarlo como parámetro a los métodos que ofrece el script.

Importante: Tu zenkipayKey es requerida, ya sea que la proporciones desde su respectivo query param al importar el script o como parámetro en los métodos de Zenkipay

1
2
3
4

<script
  type="application/javascript"
  src="https://resources.zenki.fi/zenkipay/script/zenkipay.js?zenkipayKey={your-zenkipay-key-goes-here}"
></script>

Este script genera una instancia global de ZenkiPay llamado zenkiPay que ofrece los métodos descritos aquí.

Métodos disponibles

button

Este método te permite generar un botón de pago de ZenkiPay, y para indicarle en dónde debe crearse debes pasarle como primer parámetro el ID del elemento del DOM de tu página web en donde quieres que sea insertado.

Como segundo parámetro requiere un objeto Options, de los cuales sólo son necesarios las propiedades requeridas (purchaseData y purchaseSignature). Adicionalmente, puedes modificar el estilo del botón desde la propiedad styles, aquí puedes ver las opciones de estilos disponibles.

Como parámetro final, se tiene un callback Javascript que notifica distintos eventos del proceso de pago, puedes ver su definición aquí.

A continuación se muestra un ejemplo de cómo insertar el botón de pago Zenkipay:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const idButtonContainer = "btn-pay-with-zenkipay-container";

const options = {
  purchaseData:
    '{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}',
  purchaseSignature:
    "THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=",
};

zenkiPay.button(idButtonContainer, options, handleZenkipayEvents);

function handleZenkipayEvents(error, data, details) {
  if (error) return console.error({ ...details, error });
  console.log({ ...details, data });
}

getDiscountPercentage

Este método te permite conocer si la configuración de tu comerciante tiene habilitado el descuento crypto love, retornándote el porcentage de dicho descuento, o en su defecto si lo tiene deshabilitado retornará null.

Dicho método requiere un parámetro options, de los cuales sólo son necesarios las propiedades requeridas (purchaseData y purchaseSignature). Al ejecutarlo te retornará mediante una promesa el porcentaje de descuento configurado desde el perfil de tu comercio, o en caso de que esté deshabilitado te retorará un valor null.

A continuación se muestra un ejemplo de cómo usarlo:

1
2
3
4
5
6
7
8

const options = {
  purchaseData:
    '{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}',
  purchaseSignature:
    "THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=",
};

const discountPercentage = await zenkiPay.getDiscountPercentage(options);

openModal

Este método te permite abrir la modal de pago sin hacer uso del botón de ZenkiPay.

Como primer parámetro requiere un objeto Options, de los cuales sólo son necesarios las propiedades requeridas (purchaseData y purchaseSignature). La propiedad styles es ignorada en este caso.

Como parámetro final, se tiene un callback Javascript que notifica distintos eventos del proceso de pago, puedes ver su definición aquí.

A continuación se muestra un ejemplo de cómo iniciar la modal de pago:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const options = {
  purchaseData:
    '{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}',
  purchaseSignature:
    "THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=",
};

zenkiPay.openModal(options, handleZenkipayEvents);

function handleZenkipayEvents(error, data, details) {
  if (error) return console.error({ ...details, error });
  console.log({ ...details, data });
}

Pago de pruebas

Ya que tengas preparada tu integración, procedemos a realizar un pago de pruebas desde tu sitio, para ello le damos click en el botón Haz un pago de prueba con datos firmados, lo que te mostrará una modal como la siguiente:

common-test-01

Para realizar tu pago puedes seguir nuestra guía de pagos aquí.

Realiza tu primer pago

Ya que hayas realizado correctamente tu pago de pruebas, se te mostrará un mensaje de que hemos confirmado tu primer pago de integración.

common-test-02

Prueba rápida

Si aún no has generado tus llaves pública y privada, puedes continuar con la selección de tus criptomonedas aquí.

Si ya generaste tus llaves pública y privada, y firmaste tu Purchase Data, debes continuar con tu configuración de KYC.

Integración completa

Ya que hayas realizado tu prueba con tus datos firmados con tus llaves, podemos continuar con tu selección de criptomonedas.

Definición de entidades

Nota: Las propiedades de cada entidad que tienen como sufijo un ? son opcionales, mientras que aquellas que tienen un ! son requeridas; para el caso de los parámetros aplica la misma regla del sufijo ? como opcionales.

ZenkiPay 

1
2
3
4
5
6
7
8
9

class ZenkiPay {
  button(
    containerId: string,
    options: Options,
    callback?: FnCallback
  ): Promise<void>;
  getDiscountPercentage(options: Options): Promise<number | null>;
  openModal(options: Options, callback?: FnCallback): Promise<void>;
}

Options 

1
2
3
4
5
6

class Options {
  purchaseData!: string; // PurchaseData stringified
  purchaseSignature!: string;
  zenkipayKey?: string;
  style?: Style;
}

FnCallback 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

type FnCallback = (
  error: Error | null,
  data: DoneMsg | null,
  details: MsgDetails
) => void;

class DoneMsg {
  orderId!: string;
}

class MsgDetails {
  postMsgType!: POST_MSG_TYPE;
  isCompleted!: boolean;
}

enum POST_MSG_TYPE {
  ERROR = "error",
  CANCEL = "cancel",
  CLOSE = "close",
  DONE = "done",
}

PurchaseData 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

class PurchaseData {
  country?: string;
  shopperCartId?: number | string;
  merchantOrderId?: number | string;
  shopperEmail?: string;
  purchaseSummary!: PurchaseSummary;
  items!: PurchaseItem[];
  metadata?: Metadata;
}

class PurchaseSummary {
  currency!: string;
  totalItemsAmount!: number | string;
  shipmentAmount!: number | string;
  subtotalAmount!: number | string;
  taxesAmount!: number | string;
  localTaxesAmount!: number | string;
  importCosts!: number | string;
  discountAmount!: number | string;
  additionalCharges?: AdditionalCharges;
  grandTotalAmount!: number | string;
}

class AdditionalCharges {
  [key: string]: number | string;
}

class PurchaseItem {
  itemId?: number | string;
  quantity!: number | string;
  price!: number | string;
  productName!: string;
  productDescription?: string;
  thumbnailUrl?: string;
  metadata?: Metadata;
}

class Metadata {
  [key: string]: number | string;
}

Styles 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

class Style {
  theme?: Theme;
  shape?: Shape;
  size?: Size;
  expand?: Expand;
}

type Theme = "default" | "dark" | "light";

type Shape = "default" | "pill" | "square";

type Size = "default" | "sm" | "lg";

type Expand = "default" | "block";

Ejemplos

Ejemplo de pago usando el botón de Zenkipay 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Pay with Zenkipay</title>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <main>
      <div id="btn-pay-with-zenkipay-container"></div>
    </main>
    <script
      type="application/javascript"
      src="https://resources.zenki.fi/zenkipay/script/zenkipay.js?zenkipayKey=e77e5b6662532432e9179ff4d33fe364ec88aacf9240e5e7673e474255e4a90c"
    ></script>
    <script type="application/javascript">
      const idButtonContainer = "btn-pay-with-zenkipay-container";

      const options = {
        purchaseData:
          '{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}',
        purchaseSignature:
          "THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=",
      };

      zenkiPay.button(idButtonContainer, options, handleZenkipayEvents);

      function handleZenkipayEvents(error, data, details) {
        if (error) console.error({ ...details, error });
        else console.log({ ...details, data });
      }
    </script>
  </body>
</html>

Ejemplo de pago usando los métodos getDiscountPercentage y openModal 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Pay with Zenkipay</title>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <main>
      <button id="btn-pay-with-zenkipay-container">Pay with Zenkipay</button>
    </main>
    <script
      type="application/javascript"
      src="https://resources.zenki.fi/zenkipay/script/zenkipay.js?zenkipayKey=e77e5b6662532432e9179ff4d33fe364ec88aacf9240e5e7673e474255e4a90c"
    ></script>
    <script type="application/javascript">
      const idButtonPayWithZenkipay = "btn-pay-with-zenkipay";
      const btn = document.getElementById(idButtonPayWithZenkipay);

      const options = {
        purchaseData:
          '{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}',
        purchaseSignature:
          "THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=",
      };

      zenkiPay.getDiscountPercentage(options).then((discountPercentage) => {
        if (!btn) return;

        const text = btn.innerText;
        btn.innerText = `${btn.innerText} -${discountPercentage}% Off`;
      });

      if (btn) {
        btn.addEventListener("click", () => {
          zenkiPay.openModal(options, handleZenkipayEvents);
        });
      }

      function handleZenkipayEvents(error, data, details) {
        if (error) console.error({ ...details, error });
        else console.log({ ...details, data });
      }
    </script>
  </body>
</html>