Request Signing

All requests to the Zoksh server require you to sign the request.

Only POST requests are handled.

API Keys are available under Settings > Accounts > API Keys section of your dashboard.

Signing

For all api requests, the following headers should be sent with the request:

ZOKSH-KEY: Your Account Id.

ZOKSH-TS: Unix timestamp i.e. number of milliseconds since Unix epoch.

ZOKSH-SIGN: SHA256 HMAC of the following three strings, using your Secret Key.

1. Request timestamp in miliseconds (e.g. 1635713520060), same as ZOKSH-TS.
2. Request path, including leading slash without any query parameters but not including the hostname (e.g. /v1/validate-payment).
3. Request body (JSON-encoded).

Example Node js signature calculation

  const crypto = require('crypto');

  // POST request body
  const postBody = {};
  postBody['transaction'] = '0x01c483d2deb658e7cd6beea753aad0e176ea508b517b01eab9b45bf8e03b3a15';

  // stringify the POST request body
  const postBodyJson = JSON.stringify(postBody);

  // Unix timestamp of when the request is being made. Same as ZOKSH-TS.
  const ts = new Date().getTime();
  
  // Zoksh API Server URL you are sending your POST request to.
  const requestPath = '/v1/validate-payment';

  // creating hmac object using your API Secret Key.
  const hmac = crypto.createHmac('sha256', '__Secret Key__');

  // combined string to be signed
  const toSign = `${ts}${requestPath}${postBodyJson}`;

  // ZOKSH-SIGN
  const signature = hmac.update(toSign).digest('hex');

Test data

If you have your backed written in node js, you can use the the code above to sign the requests. We will provide code in other languages in the future. Till then you can use following test data to verify your code.

Test Data 1

// postBody
{
  "prefill": {
    "name":"Demo user",
    "phone":"+91-8787878787",
    "email":"kalpanassleep@gmail.com"
  },
  "amount":"70",
  "fiat":"USD",
  "label":"Sneaker NFT #3125 EI35",
  "merchant":{
    "desc":"",
    "extra":"something here",
    "orderId":"some_order_id_here"
  }
}

// ZOKSH-KEY or Account ID
627b4a2836b59026e4d5cd6c

// requestPath
/v2/order

// timestamp
1669891598013

// Secret Key
sk_test_EM+cYhQ50tBO31PAVEifGw==

// toSign
1669891598013/v2/order{"prefill":{"name":"Demo user","phone":"+91-8787878787","email":"kalpanassleep@gmail.com"},"amount":"70","fiat":"USD","label":"Sneaker NFT #3125 EI35","merchant":{"desc":"","extra":"something here","orderId":"some_order_id_here"}}

// Signature
76f13e124e09925822c3a2058bdca7833626bd5f388b9238c5a3d04f53f9835b

Test Data 2

// postBody
{
  "prefill": {
    "name":"Demo user 2",
    "phone":"+91-9999999999",
    "email":"demouser2@gmail.com"
  },
  "amount":"700",
  "fiat":"USD",
  "label":"Shining Moneky NFT",
  "merchant":{
    "desc":"",
    "extra":"something extra here",
    "orderId":"merchant_local_merchant_id"
  }
}
 
// ZOKSH-KEY or Account ID
627b4a2836b59026e4d5cd6c
 
// timestamp
1669891267262
 
// requestPath
/v2/order
 
// Secret Key
sk_test_EM+cYhQ50tBO31PAVEifGw==
 
// toSign
1669891267262/v2/order{"prefill":{"name":"Demo user 2","phone":"+91-9999999999","email":"demouser2@gmail.com"},"amount":"700","fiat":"USD","label":"Shining Moneky NFT","merchant":{"desc":"","extra":"something extra here","orderId":"merchant_local_merchant_id"}}
 
// Signature
b01e2ace1d4a417be08815aad365e9d728ada80d1511ed47b8f7143f307ad79e