Preparations for your integration

To start the full integration, we must first configure your public and private keys, to do this you must click on the Generate a key pair button.

generate-keys-01

This action will open a modal where you must choose how you want to generate your keys.

generate-keys-02

Help me create a pair of keys for me

By selecting this option, you only have to save the keys that we generate for you.

generate-keys-03

When clicking on the Continue button, you must make sure that you have saved at least your private key, since it will be of vital importance that you store it in a safe place on your server.

generate-keys-05

I would like to generate and upload my own keys

When selecting this option, you must generate your own public and private keys, for this you can follow our guide here. We recommend that you do not generate these keys on any website, as your private key could be compromised.

Once you have generated your keys, just share with us only your public key.

generate-keys-04

Integration with your server

For security reasons and integrity of the information, you must sign with your RSA SHA256 private key the detail of the purchase to be paid, which must be an instance of PurchaseData as a JSON object, we recommend generating your instance from your server for security and integrity reasons; Here is an example:

 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


{
  "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"
  }
}

Important: Make sure that the sum of the fields of purchaseSummary corresponds to grandTotalAmount , since Otherwise, the payment cannot be made. If any of the purchaseSummary fields do not apply to your payment order, you can assign a 0 value.

Once you have your instance of PurchaseData , we proceed to transform it into a text string; As an example, in Javascript you can use the JSON.stringify(purchaseData) method, but it will depend on the technology you use on your server, here is an example of your instance transformed to a string:

1

'{"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"}}'

We continue signing your text string with your RSA SHA256 private key , since, for security and information integrity reasons, you must sign with your RSA SHA256 private key in format base64 , you can follow the instructions we have here . We will name this signature purchaseSignature.

This is an example of your purchaseSignature :

1

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=

Having your text string of your PurchaseData and your purchaseSignature , we can continue with the integration by selecting one of the following options:

Definition of entities

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

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