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 Dashboardx-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
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:
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.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.
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.
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
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:
Combine the merchant id,
x-timestamp
header value (request timestamp), method and transaction id (payin/payout id). You can find the example below.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.
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
Last updated