Authentication

Request headers

Every request towards Kitopay API must contain the following headers:

  • x-merchant-id - the id of the merchant that you can find in the Dashboard

  • x-signature - the request signature generated using HMAC-SHA256 (check the signature generation algorithm section for more details)

  • x-timestamp - UNIX timestamp of the request . If x-timestamp differs from the server time by more than 60 seconds the request will be considered expired.

Signature generation

x-signature

To generate the digital signature using Hash-based Message Authentication Code (HMAC-SHA256), you need to use the request URL, body, method, merchant id and timestamp. The whole algorithm is outlined below:

  1. Combine the merchant id, x-timestamp header value (request timestamp), method, the entire request URL with query string parameters and request body without any delimiters. You can find the example below.

  2. Use the HMAC-SHA256 algorithm with the secret key retrieved in the dashboard to get the hash of the string generated in the 1st step. Data must be encoded using UTF8 while computing the hash.

  3. The resulting hash is the signature that you need to pass in the x-signature header for this API request.

You can use the example provided below to check if your integration is correct.

Signature generation example

You should use the request body, x-timestamp and x-merchant-id headers values for signature generation. The payload, timestamp and merchant id used for signature generation must be 100% the same as the payload and headers sent in the request.

It is important to use the exact payload that will be sent in the request. If you use a formatted ("pretty") JSON for signature generation and then automatically minify or escape the JSON in the request, signature validation will fail.

One of the most common integration issues you can face is a trailing slash error (missing or extra trailing slash). Please make sure to use the exact URL that you will be sending the request to in the payload for signature generation.

We'll use the following x-timestamp, x-merchant-id and secret key values in the example below: 

x-timestamp = 1601234567
x-merchant-id = dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148
secret key = dev_sec_7HdEmJy9NXTc3S7LMYEf92FAUeThRSTyHFgHBMH78YKz2uQho596jEУvEiERKDm9

POST https://api.dev.kitopay.com/api/v1/merchants/payins/

 {
  "reference_id": "tx-123",
  "payment": {
    "amount": 49.23,
    "currency": "EUR"
  },
  "customer": {
    "id": "1",
    "first_name": "Salvador",
    "last_name": "Dali",
    "date_of_birth": "1904-05-11",
    "email": "[email protected]",
    "phone": {
      "country_code": "+34",
      "number": "696123456"
    },
    "address": {
      "addr_line_1": "Placa Gala i Salvador Dali, 5", 
      "city": "Figueres",
      "country": "ES",
      "zip": "17600"
    }
  },
  "redirect_urls": {
    "success": "https://website.com/cashier-result-page/success",
    "fail": "https://website.com/cashier-result-page/fail"
  },
  "webhook_url": "https://api.dev.website.com/webhooks/kitopay",
  "browser_data": {
    "ip_address": "195.138.66.113",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.2 Safari/605.1.15"
  },
  "language": "en"
}

The payload should look like this:

You will get the signature:

x-signature = 8c01e88d03370dc85b70000c9f1e9f0bd53d95b236faa72e9d26b7209f14087b

For GET requests:

Example 1:

We'll use the following x-timestamp, x-merchant-id, secret key and payin id values in the example below: 

x-timestamp = 1601234567
x-merchant-id = dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148
secret key = dev_sec_7HdEmJy9NXTc3S7LMYEf92FAUeThRSTyHFgHBMH78YKz2uQho596jEУvEiERKDm9
payin id = 38f70928-d7a4-4b7c-bbe7-e74be1f273df

GET https://api.dev.kitopay.com/api/v1/merchants/payins/38f70928-d7a4-4b7c-bbe7-e74be1f273df

The payload should look like this:

dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa71481601234567GEThttps://api.dev.kitopay.com/api/v1/merchants/payins/38f70928-d7a4-4b7c-bbe7-e74be1f273df

You will get the signature:

x-signature = d41b43284c8689d932139216b21c5e9bf1ac742bbcc0d885fcde43563349f45c

Example 2:

We'll use the following x-timestamp, x-merchant-id, secret key and reference_id values in the example below: 

x-timestamp = 1601234567
x-merchant-id = dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148
secret key = dev_sec_7HdEmJy9NXTc3S7LMYEf92FAUeThRSTyHFgHBMH78YKz2uQho596jEУvEiERKDm9
reference_id = merchant-internal-id-123

GET https://api.dev.kitopay.com/api/v1/merchants/transactions/?reference_id=merchant-internal-id-123

The payload should look like this:

dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa71481601234567GEThttps://api.dev.kitopay.com/api/v1/merchants/payins/?reference_id=merchant-internal-id-123

You will get the signature:

x-signature = cfae1df0778182d14833accea93825a72738f6ea69451af7c000c5b8fbae2aa2

x-simplified-signature

To generate the digital signature using Hash-based Message Authentication Code (HMAC-SHA256), you only need to use the merchant id, timestamp and transaction id (full request body is not required). The whole algorithm is outlined below:

  1. Combine the merchant id, x-timestamp header value (request timestamp), method and transaction id (payin/payout id). You can find the example below.

  2. Use the HMAC-SHA256 algorithm with the secret key retrieved in the dashboard to get the hash of the string generated in the 1st step. Data must be encoded using UTF8 while computing the hash.

  3. The resulting hash is the signature that you need to pass in the x-simplified-signature header for this API request.

You can use the example provided below to check if your integration is correct.

Signature generation example

We'll use the following x-timestamp, x-merchant-id and secret key values in the example below: 

x-timestamp = 1601234567
x-merchant-id = dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148
secret key = dev_sec_7HdEmJy9NXTc3S7LMYEf92FAUeThRSTyHFgHBMH78YKz2uQho596jEУvEiERKDm9

POST https://sandbox.pci-proxy/v1/push/123qREW/

{
  "payin_id": "15769562-9bee-4e25-be6c-f6969251156f",
  "card": {
    "pan": "4242424242424242",
    "exp_month": "06",
    "exp_year": "2025",
    "csc": "048"
  }
}

The payload should look like this:

dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148160123456715769562-9bee-4e25-be6c-f6969251156f

You will get the signature:

x-simplified-signature = 08e81ac37400b8a4c9b4c7e0cc7bc570588b0b1208ec2a3ffe783bdeac293727
PreviousChangelogNextAPI Reference

Last updated