Events Signature

Every notification we send to your endpoint is signed. We do this by including a header named "SmartFastPay-Signature" in every event we send. This allows you to verify and ensure that the event was sent by SmartFastPay and not a third party.

The "SmartFastPay-Signature" header contains a timestamp and one or more signatures. The timestamp is prefixed by t= and each signature is prefixed by a schema. Schemas start with v followed by an integer. Currently there is only one signature schema which is v1.

Exemplo do Header SmartFastPay-Signature:

SmartFastPay-Signature: t=1681235417000,v1=b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8

Signatures are generated using a hashed message based authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you must ignore all non-v1 schemas.

How to validate the signature

Step 1: Extract the Timestamp and Signature from the Header

Split the header using the character as a separator to get the list of elements. Once that's done, do another split using the = character as a separator, to get the prefix and the value.

The value obtained from the t prefix corresponds to the timestamp and the v1 corresponds to the signature. You can discard other values.

Step 2: Prepare the string to compare signatures

You must concatenate this information:

The timestamp (as string)
The character .
The JSON payload (request body, in string format)

Compute the HMAC with the SHA256 hash function. Use the secret (see what your secret is by ).

Example in PHP:

<?php

// This secret is not the secret of the authentication token, it is the UID
$secret = 'my-secret';

// This is the "t" value received on SmartFastPay-Signature header
$timestamp = 1681235417000;

$requestPayload = [
    'callback' => true,
    'value' => 'value-field'
];

$jsonPayload = json_encode($requestPayload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

$paramsSignature = "{$timestamp}.{$jsonPayload}";

echo hash_hmac('sha256', $paramsSignature, $secret);

// Output: b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8

Step 3: Compare signatures

Compare the signature sent by SmartFastPay in the Header with the signature you generated in Step 2.

Example in PHP:

<?php

// Comparing Signatures
// Example Header of the request sent by SmartFastPay:
$headers = [
    'SmartFastPay-Signature' => 't=1681235417000,v1=b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8'
];

// Extract the value of 't' from Header 'SmartFastPay-Signature'
// '1681235417000'
$timestamp = explode("=", explode(",", $headers['SmartFastPay-Signature'])[0])[1];

// Extract the value of 'v1' from Header 'SmartFastPay-Signature'
// 'b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8'
$signature = explode("=", explode(",", $headers['SmartFastPay-Signature'])[1])[1];

// The Signature you generated in Step 2 must be equal to the value of the "$signature" variable.
// Must return 1 (true)
echo ('yourSignature' === $signature);

<?php // This secret is not the secret of the authentication token, it is the UID $secret = 'my-secret'; // This is the "t" value received on SmartFastPay-Signature header $timestamp = 1681235417000; $requestPayload = [ 'callback' => true, 'value' => 'value-field' ]; $jsonPayload = json_encode($requestPayload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); $paramsSignature = "{$timestamp}.{$jsonPayload}"; echo hash_hmac('sha256', $paramsSignature, $secret); // Output: b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8

<?php // Comparing Signatures // Example Header of the request sent by SmartFastPay: $headers = [ 'SmartFastPay-Signature' => 't=1681235417000,v1=b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8' ]; // Extract the value of 't' from Header 'SmartFastPay-Signature' // '1681235417000' $timestamp = explode("=", explode(",", $headers['SmartFastPay-Signature'])[0])[1]; // Extract the value of 'v1' from Header 'SmartFastPay-Signature' // 'b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8' $signature = explode("=", explode(",", $headers['SmartFastPay-Signature'])[1])[1]; // The Signature you generated in Step 2 must be equal to the value of the "$signature" variable. // Must return 1 (true) echo ('yourSignature' === $signature);