Authentication
The Transactli REST API for merchants uses API keys combined with signatures to authenticate requests.
Each merchant will receive a combination of an API key and an API secret, which they will then use to authenticate API requests.
Signature
The signature is generated using the HMAC-SHA256 algorithm. It combines method, path (with query), request body, a UNIX timestamp, and the API_SECRET (provided to the merchant) into a single string. This string is then hashed using SHA-256. The timestamp is also included in the request as a separate header.
public static class SignatureGenerator
{
public static string GenerateSignature(string method, string path, string body, string secretKey)
{
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
var signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{method}|{path}|{timestamp}|{body}"));
return Convert.ToBase64String(signatureBytes);
}
}
function generateSignature(method, path, body, secretKey) {
const timestamp = Math.floor(Date.now() / 1000).toString();
const payload = `${method}|${path}|${timestamp}|${body}`;
return CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(payload, secretKey));
}
function generateSignature($method, $path, $body, $secretKey) {
$timestamp = time();
$payload = "{$method}|{$path}|{$timestamp}|{$body}";
$signature = hash_hmac('sha256', $payload, $secretKey, true);
return base64_encode($signature);
}
def generate_signature(method, path, body, secret_key):
timestamp = str(int(time.time()))
payload = f"{method}|{path}|{timestamp}|{body}"
signature = hmac.new(
secret_key.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
)
return base64.b64encode(signature.digest()).decode('utf-8')
public static String generateSignature(String method, String path, String body, String secretKey) {
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
String payload = String.format("%s|%s|%s|%s", method, path, timestamp, body);
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] signatureBytes = sha256_HMAC.doFinal(payload.getBytes("UTF-8"));
return Base64.getEncoder().encodeToString(signatureBytes);
}
The payload before being hashed should look like this:
POST|/merchant/v1/purchase/init|1757688663|{"cryptoAllowedSlippage":"0.1","externalOrderId":"OrderId","fiatCurrency":"EUR","lineItems":[{"quantity":1,"price":10,"name":"test","description":"description"}],"timeout":10000,"totalPrice":10,"kyc":{"email":"user@email.com","phoneNumber":"+xxxxxxxxxx","firstName":"firstName","lastName":"lastName","dateOfBirth":"2000-01-01","countryTax":"IT"},"merchantCustomData":"user123-session456-id567"}
Where:
POST → method
/merchant/v1/purchase/init → path
1757688663 → timestamp (Unix seconds)
Final segment → raw JSON request body (minified, no spaces)
GET Request Authentication Example
When sending a GET request, the authentication headers are generated in the same way as for POST requests. The only difference is that the request body is empty ("").
The payload before being hashed should look like this:
GET|/merchant/v1/purchase|1757688663|
With every request you should send the following headers:
Header | Description |
|---|
X‑API‑KEY | API key provided by Transactli, used for Merchant identification |
X‑SIGNATURE | Cryptographic signature for authenticating request payload, with API-SECRET |
TIMESTAMP | UNIX timestamp when signature was calculated. |
User-Agent | Required for server-side requests (automatically included in browser requests) |
09 January 2026