Authentication

All API requests require two headers: an API key and an HMAC signature for security.

Required Headers

Header	Description
`X-API-Key`	Your partner API key (e.g., `hpk_sandbox_...`)
`X-Signature`	HMAC-SHA256 signature of the request body
`Content-Type`	`application/json`

API Keys

API keys are prefixed to indicate their environment:

Sandbox Keys

hpk_sandbox_xxxxxxxxxxxxxxxx

For testing, no real money

Production Keys

hpk_prod_xxxxxxxxxxxxxxxx

For live transactions

HMAC Signature

Every request must include an HMAC-SHA256 signature. Here's how to generate it:

Signature Steps

1 Canonicalize the JSON body (sort keys alphabetically, remove whitespace)
2 Compute HMAC-SHA256 using your API secret
3 Encode as lowercase hexadecimal string

Python Example

Python

import hmac
import hashlib
import json

def generate_signature(payload: dict, secret: str) -> str:
    # Step 1: Canonicalize (sort keys, no whitespace)
    canonical = json.dumps(payload, separators=(',', ':'), sort_keys=True)
    
    # Step 2 & 3: HMAC-SHA256 → hex string
    signature = hmac.new(
        secret.encode('utf-8'),
        canonical.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return signature

# Usage
payload = {
    "partner_reference": "ORDER-001",
    "amount": "100.00",
    "currency": "USD"
}
api_secret = "hps_sandbox_your_secret"
signature = generate_signature(payload, api_secret)

PHP Example

PHP

<?php
function generateSignature(array $payload, string $secret): string
{
    // Sort keys recursively
    ksort($payload);
    
    // Canonicalize (no whitespace)
    $canonical = json_encode($payload, JSON_UNESCAPED_SLASHES);
    
    // HMAC-SHA256
    return hash_hmac('sha256', $canonical, $secret);
}

// Usage
$payload = [
    'partner_reference' => 'ORDER-001',
    'amount' => '100.00',
    'currency' => 'USD'
];
$apiSecret = 'hps_sandbox_your_secret';
$signature = generateSignature($payload, $apiSecret);

Node.js Example

JavaScript

const crypto = require('crypto');

function generateSignature(payload, secret) {
    // Sort keys and canonicalize
    const sortedPayload = Object.keys(payload)
        .sort()
        .reduce((obj, key) => ({ ...obj, [key]: payload[key] }), {});
    
    const canonical = JSON.stringify(sortedPayload);
    
    // HMAC-SHA256
    return crypto
        .createHmac('sha256', secret)
        .update(canonical)
        .digest('hex');
}

// Usage
const payload = {
    partner_reference: 'ORDER-001',
    amount: '100.00',
    currency: 'USD'
};
const apiSecret = 'hps_sandbox_your_secret';
const signature = generateSignature(payload, apiSecret);

Test Your Signature

Use our signature generator tool to verify your implementation:

Open Signature Generator

Previous Overview

Next Pay User