Zenki
Zenki Home Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Zenki Documentation
  2. /
  3. Zenkipay
  4. /
  5. Integration Process
  6. /
  7. Integration Mechanisms
  8. /
  9. Integration with our Javascript script

Integration with our Javascript script

When you click on the Continue button, a code snippet will be shown that you must copy and/or adapt in your website, this snippet has an example of how you can integrate it.

script

To integrate the Zenkipay script, you need to add it to your site, we recommend adding your zenkipayKey as a query param, which you can extract from the snippet; otherwise you can also pass it as a parameter to the methods offered by the script.

Important: Your zenkipayKey is required, whether you provide it from its respective query param when importing the script or as a parameter in Zenkipay methods.

1
2
3
4

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

This script generates a global ZenkiPay instance called zenkiPay that provides the methods described here.

Available methods

button

This method allows you to generate a ZenkiPay payment button, and to indicate where it should be created you must pass as first parameter the ID of the DOM element of your web page where you want it to be inserted.

As a second parameter it requires an Options object, of which only the required properties(purchaseData and purchaseSignature) are needed. Additionally, you can modify the style of the button from the styles property, here you can see the available style options.

As a final parameter, we have a Javascript callback that notifies different events of the payment process, you can see its definition here.

Below is an example of how to insert the Zenkipay payment button:

 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

This method allows you to know if your merchant’s configuration has the crypto love discount enabled, returning the percentage of the discount, or if it is disabled it will return null.

This method requires an options parameter, of which only the required properties(purchaseData and purchaseSignature) are needed. When executed, it will return a promise with the discount percentage configured from your commerce profile, or in case it is disabled, it will return a null value.

An example of how to use it is shown below:

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

This method allows you to open the payment method without using the ZenkiPay button.

As first parameter requires an Options object, of which only the required properties (purchaseData and purchaseSignature) are needed. The styles property is ignored in this case.

As a final parameter, we have a Javascript callback that notifies different events of the payment process, you can see its definition here.

Below is an example of how to initiate the payment method:

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

Test payment

Once you have prepared your integration, we proceed to make a test payment from your site, to do this we click on the button Make a test payment with signed data, which will show you a modal like the following:

common-test-01

To make your payment you can follow our payment guide here.

Make your first payment

Once you have successfully completed your test payment, you will be shown a message that we have confirmed your first integration payment.

common-test-02

Simple test

If you haven’t generated your public and private keys yet, you can continue with the selection of your cryptocurrencies here.

If you already generated your public and private keys, and sign your Purchase Data, you must continue with your KYC setup.

Full integration

Once you have done your test with your data signed with your keys, we can continue with your selection of cryptocurrencies.

Definition of entities

Note: The properties of each entity that are suffixed with a ? are optional, while those with a ! are required; for the case of parameters the same rule applies as for the ? suffix as optional.

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";

Examples

Example of payment using the Zenkipay button 

 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>

Example of payment using getDiscountPercentage and openModal methods 

 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>