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

{
    "id": "e4dd60bb-574f-4a13-910a-57c9795d905f",
    "bankStatus": "ACSC",
    "statusGroup": "completed",
    "type": "PAYMENT"
}

Refund

{
    "id": "1", 
    "paymentId": "e4dd60bb-574f-4a13-910a-57c9795d905f",
    "statusGroup": "completed",
    "type": "PAYMENT_REFUND" 
}

It’s strongly advised to use a raw request body for the hash computing process.

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 [e-mail].

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

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

Node.js

Make sure that received webhook is authentic. The example below is written using kevin. Node.js library.

const kevin = require('@kevin.eu/kevin-platform-client');

const endpointSecret = 'my-endpoint-secret';

const securityManager = new kevin.SecurityManager(endpointSecret);

// webhook request headers object
const headers = req.headers;

// webhook request body object
const body = req.body;

// URL to which webhook was requested
const webhookUrl = 'https://example.com/notify?orderId=123';

// Timestamp timeout in milliseconds
const timestampTimeout = '300000';

const isWebhookSignatureValid = securityManager.verifySignature(body, headers, webhookUrl, timestampTimeout); 

Pseudocode

httpMethod = 'POST'
requestUrl = 'https://yourapp.com/notify'
timestamp = '1600000000000'
endpointSecret = 'SECRET'

// Bank payment payload:
requestBody = '{"id":"e4dd60bb-574f-4a13-910a-57c9795d905f","bankStatus":"ACSC","statusGroup":"completed","type":"PAYMENT"}'
expectedSignature = 0a3ac91865c78ac9b675129f24ee3f25a71b02d1e83976833f0f139db6508777

// Card payment payload:
requestBody = '{"id":"e4dd60bb-574f-4a13-910a-57c9795d905f","cardStatus":"paid","statusGroup":"completed","type":"PAYMENT"}'
expectedSignature = 54cf5691f8d121f3b79bc1d102709975ff2ad39143e189043841c9c55fbe0902

// Hybrid payment payload:
requestBody = '{"id":"e4dd60bb-574f-4a13-910a-57c9795d905f","hybridStatus":"created","statusGroup":"completed","type":"PAYMENT"}'
expectedSignature = 4492b9761e7897b7f532706ea7bf87c1f9f7d6f1513d10c1c76ee0e41b9986ee

data = httpMethod + requestUrl + timestamp + requestBody
signature = HMAC_SHA256(data, endpointSecret)