Payment verification
As soon as payment or refund succeeds or fails, kevin. sends you a webhook. Webhooks are just HTTP POST requests to your web server. Your Webhook-URL must return a response with a 200 HTTP status code. Any other HTTP response code will be considered as a failure. It is not required for your webhook response to return any content. We will retry failed webhooks periodically for up to two days until we receive a response with 200 HTTP status code.
Webhook is just a signal about the final payment status, which cannot be changed. If you need any additional information about the payment, you have to fetch it independently using the getPayment endpoint or attach your own query parameters to your Webhook-URL. Below you can find the example of a webhook request:
Bank payment
Card payment
Hybrid payment
Refund
{
"id": "e4dd60bb-574f-4a13-910a-57c9795d905f",
"bankStatus": "ACSC",
"statusGroup": "completed",
"type": "PAYMENT"
}
{
"id": "e4dd60bb-574f-4a13-910a-57c9795d905f",
"cardStatus": "expired",
"statusGroup": "failed",
"type": "PAYMENT"
}
{
"id": "e4dd60bb-574f-4a13-910a-57c9795d905f",
"hybridStatus": "expired",
"statusGroup": "failed",
"type": "PAYMENT"
}
{
"id": "1",
"paymentId": "e4dd60bb-574f-4a13-910a-57c9795d905f",
"statusGroup": "completed",
"type": "PAYMENT_REFUND"
}
Webhooks do not confirm that money is received. If bank supports instant payments, funds are received in a couple of minutes. Otherwise, the transaction will be settled within 1-3 work days.
In order to meet all security requirements, kevin. signs every webhook request. The request contains two headers:
  • X-Kevin-Timestamp - the timestamp in milliseconds when the request was sent by kevin.
  • X-Kevin-Signature - the signature which is computed using the HMAC-SHA256 algorithm.
You can validate the signature by combining the uppercase HTTP method of the request, the request URL, timestamp and the request body into one single string and then generating it using the HMAC-SHA256 algorithm with your endpointSecret.
ATTENTION: Client Secret is different key. If you do not have yourEndpoint Secret, please email [email protected].

Computing signature hash

We recommend rejecting the webhook request if the signature is older than 5 minutes.
Below you can find the signature generation code for webhook request confirmation:
PHP
Pseudocode
The example below is written using kevin. PHP library.
use Kevin\SecurityManager;
​
$endpointSecret = 'your-endpoint-secret';
$webhookUrl = 'your-webhook-url';
​
// Timestamp is provided in milliseconds
$timestampTimeout = 300000;
​
$requestBody = file_get_contents('php://input');
$headers = getallheaders();
​
$isValid = SecurityManager::verifySignature(
$endpointSecret,
$requestBody,
$headers,
$webhookUrl,
$timestampTimeout
);
​
http_response_code(200);
httpMethod = 'POST'
requestUrl = 'https://yourapp.com/notify'
timestamp = '1600000000000'
endpointSecret = 'SECRET'
requestBody = '{"id":"e4dd60bb-574f-4a13-910a-57c9795d905f","status":"ACSC","statusGroup":"completed","type":"PAYMENT"}'
​
data = httpMethod + requestUrl + timestamp + requestBody
signature = HMAC_SHA256(data, endpointSecret)
If your algorithm is correct, the expected signature value from the code above is 545d0df9a2cd90c92f9008416e01792815ceccfe9d63262636912b8ce14903ad.
Copy link