Request Signature

Learn how to sign your API requests for secure communication

How Signature Works

All API requests must be signed using HMAC-SHA256 algorithm. The signature ensures that the request is authentic and has not been tampered with.

Security

The signature mechanism provides request authentication and integrity verification. Keep your API Secret secure and never expose it in client-side code.

Request Headers

Header	Description	Example
`X-API-Key`	Your API Key	`pk_live_abc123...`
`X-Signature`	HMAC-SHA256 signature (hex encoded)	`a1b2c3d4e5f6...`
`X-Timestamp`	Unix timestamp in seconds	`1705320000`

Signature Format

The signature is calculated by concatenating the following values and hashing with HMAC-SHA256:

message = timestamp + method + path + body

Component	Description	Example
`timestamp`	Unix timestamp in seconds (string)	`"1705320000"`
`method`	HTTP method (uppercase)	`"POST"` or `"GET"`
`path`	Request path including query string	`"/v1/deposit"`
`body`	JSON stringified request body (empty string for GET)	`'{"amount":1000}'`

Timestamp Validation

The timestamp must be within 5 minutes of the server time to prevent replay attacks.

Example Implementation

JavaScript / Node.js

const crypto = require('crypto');

function generateSignature(apiSecret, timestamp, method, path, body = '') {
  // Concatenate the message components
  const message = timestamp + method + path + body;

  // Generate HMAC-SHA256 signature
  return crypto
    .createHmac('sha256', apiSecret)
    .update(message)
    .digest('hex');
}

// Example usage
const apiSecret = 'your-api-secret';
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = 'POST';
const path = '/v1/deposit';
const body = JSON.stringify({
  processId: 'ORDER-12345',
  amount: 1000,
  currency: 'TRY',
  customer: { id: 'user-123', name: 'John Doe', username: 'johndoe' }
});

const signature = generateSignature(apiSecret, timestamp, method, path, body);
console.log('Signature:', signature);

PHP

<?php

function generateSignature($apiSecret, $timestamp, $method, $path, $body = '') {
    // Concatenate the message components
    $message = $timestamp . $method . $path . $body;

    // Generate HMAC-SHA256 signature
    return hash_hmac('sha256', $message, $apiSecret);
}

// Example usage
$apiSecret = 'your-api-secret';
$timestamp = (string) time();
$method = 'POST';
$path = '/v1/deposit';
$body = json_encode([
    'processId' => 'ORDER-12345',
    'amount' => 1000,
    'currency' => 'TRY',
    'customer' => ['id' => 'user-123', 'name' => 'John Doe', 'username' => 'johndoe']
]);

$signature = generateSignature($apiSecret, $timestamp, $method, $path, $body);
echo "Signature: " . $signature;

Python

import hmac
import hashlib
import json
import time

def generate_signature(api_secret, timestamp, method, path, body=''):
    # Concatenate the message components
    message = f"{timestamp}{method}{path}{body}"

    # Generate HMAC-SHA256 signature
    signature = hmac.new(
        api_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return signature

# Example usage
api_secret = 'your-api-secret'
timestamp = str(int(time.time()))
method = 'POST'
path = '/v1/deposit'
body = json.dumps({
    'processId': 'ORDER-12345',
    'amount': 1000,
    'currency': 'TRY',
    'customer': {'id': 'user-123', 'name': 'John Doe', 'username': 'johndoe'}
})

signature = generate_signature(api_secret, timestamp, method, path, body)
print(f"Signature: {signature}")

C#

using System;
using System.Security.Cryptography;
using System.Text;

public static string GenerateSignature(
    string apiSecret,
    string timestamp,
    string method,
    string path,
    string body = "")
{
    // Concatenate the message components
    string message = timestamp + method + path + body;

    // Generate HMAC-SHA256 signature
    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
    {
        byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
        return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
    }
}

// Example usage
string apiSecret = "your-api-secret";
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
string method = "POST";
string path = "/v1/deposit";
string body = "{\"processId\":\"ORDER-12345\",\"amount\":1000}";

string signature = GenerateSignature(apiSecret, timestamp, method, path, body);
Console.WriteLine($"Signature: {signature}");

Request Example

cURL Example

curl -X POST https://<service_name>.api.wiapay.co/v1/deposit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_abc123..." \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Timestamp: 1705320000" \
  -d '{
    "processId": "ORDER-12345",
    "amount": 1000,
    "currency": "TRY",
    "customer": {
      "id": "user-123",
      "name": "John Doe",
      "username": "johndoe"
    }
  }'

Error Responses

Error Code	Description	Solution
`INVALID_SIGNATURE`	Signature verification failed	Check your signature generation logic and API Secret
`MISSING_SIGNATURE`	X-Signature header not provided	Include X-Signature header in your request
`TIMESTAMP_EXPIRED`	Request timestamp is too old	Use current timestamp and sync your server clock
`MISSING_TIMESTAMP`	X-Timestamp header not provided	Include X-Timestamp header in your request