EPaySe
Authentication

Authentication

Learn how to authenticate API requests using HMAC-SHA256 signatures for maximum security.

Overview

EPaySe uses HMAC-SHA256 signatures to authenticate API requests. Every request must include your API key and a signature generated using your API secret. This ensures that requests are authentic and haven't been tampered with.

API Keys

API keys are used to identify your account and authenticate requests. Each key consists of two parts:

Key Types

  • Sandbox Keys - sk_sandbox_... - For testing and development. No real money is processed.
  • Production Keys - sk_live_... - For live transactions. Real payments are processed.

Generating API Keys

  1. Log in to your EPaySe dashboard
  2. Navigate to Settings → API Keys
  3. Click "Create API Key"
  4. Save both the API Key and API Secret securely

HMAC Signature

HMAC (Hash-based Message Authentication Code) signatures ensure request integrity and authenticity. Each request must include these headers:

Required Headers

  • X-Api-Key-Id: Your API key
  • X-Signature: HMAC-SHA256 signature
  • X-Timestamp: Unix timestamp
  • X-Nonce: Unique random string

📝 Signature Format

The HMAC signature is generated using the following format:

HMAC-SHA256(secret_key, "METHOD|PATH|TIMESTAMP|BODY")

Example: POST|api/v1/transaction/create|1699564800|{"amount":100}

Example Request

HTTP
Example API Request with HMAC Headers
POST /api/v1/transaction/create HTTP/1.1
Host: api.epayse.com
Content-Type: application/json
X-Api-Key-Id: your_api_key_here
X-Signature: generated_hmac_signature
X-Timestamp: 1699564800
X-Nonce: unique_nonce_string

{
  "amount": 100.00,
  "currency": "USD",
  "redirectUrl": "https://yoursite.com/success"
}

cURL Example with HMAC Headers

Bash
Complete cURL Request
curl -X POST "https://api.epayse.com/api/v1/transaction/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-Id: your_api_key_here" \
  -H "X-Signature: generated_hmac_signature" \
  -H "X-Timestamp: 1699564800" \
  -H "X-Nonce: unique_nonce_string" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "redirectUrl": "https://yoursite.com/success"
  }'

🧪 Test HMAC Authentication

Try making an authenticated request to test your API credentials. This example uses the Currencies API endpoint.

GET
/api/v1/currencies

Test HMAC authentication with a simple GET request

Copy this prompt to Claude, ChatGPT, Gemini, or any AI assistant for implementation help 

Help me implement an API call to this endpoint:

**Endpoint Details:**
- Method: GET
- URL: undefined
- Content-Type: application/json

**Authentication:**
This endpoint requires HMAC-SHA256 authentication with the following headers:
- X-Api-Key-Id: [Your API Key ID]
- X-Signature: [HMAC-SHA256 signature]
- X-Timestamp: [Unix timestamp]
- X-Nonce: [Unique random string]

**HMAC Signature Generation:**
The signature is computed as: HMAC-SHA256(secret_key, data_to_sign)
Where data_to_sign = METHOD|PATH|TIMESTAMP|BODY
Example: GET|api/v1/currencies|1234567890|{"key":"value"}

**Requirements:**
1. Implement proper error handling
2. Add request timeout (30 seconds recommended)
3. Generate HMAC signature correctly
4. Include all required authentication headers
5. Parse and return the JSON response
6. Handle different HTTP status codes (200, 400, 500, etc.)

**Expected Response Format:**
```json
{
  "status": "SUCCESS" | "ERROR",
  "message": "Success message or error description",
  "data": { ... }
}
```

Please provide working code in [YOUR_LANGUAGE] with best practices and comments.

💡 Pro Tip:

After copying, paste this prompt into Claude, ChatGPT, or Gemini and specify your programming language. The AI will generate complete, working code with proper error handling and HMAC authentication.

Using Official SDKs

Our official SDKs handle authentication automatically. Just provide your API credentials:

PHP SDK

PHP
<?php
use EPaySe\Client;
use EPaySe\Security\HmacSigner;

$apiKey = 'sk_live_your_api_key_here';
$apiSecret = 'your_api_secret_here';

// Initialize client
$client = new Client([
    'api_key' => $apiKey,
    'api_secret' => $apiSecret,
    'environment' => 'production'
]);

// Create transaction (HMAC signature automatically generated)
$transaction = $client->transactions->create([
    'amount' => 10000,
    'currency' => 'USD',
    'customer_email' => '[email protected]',
]);

echo $transaction->id;

JavaScript SDK

JavaScript
import { EPaySeClient } from '@epayse/sdk';

const client = new EPaySeClient({
  apiKey: 'sk_live_your_api_key_here',
  apiSecret: 'your_api_secret_here',
  environment: 'production'
});

// Create transaction (HMAC signature automatically generated)
const transaction = await client.transactions.create({
  amount: 10000,
  currency: 'USD',
  customerEmail: '[email protected]',
});

console.log(transaction.id);

Python SDK

Python
from epayse import Client

client = Client(
    api_key='sk_live_your_api_key_here',
    api_secret='your_api_secret_here',
    environment='production'
)

# Create transaction (HMAC signature automatically generated)
transaction = client.transactions.create(
    amount=10000,
    currency='USD',
    customer_email='[email protected]',
)

print(transaction.id)

Manual Implementation

If you're not using an SDK, you'll need to generate HMAC signatures manually.

Signature Generation Steps

  1. Create a signature base string from: HTTP method + path + timestamp + nonce + request body
  2. Generate HMAC-SHA256 hash using your API secret as the key
  3. Prefix the hash with 'sha256='
  4. Include the signature in the X-Signature header

Manual Implementation Example

PHP Example

PHP
Manual HMAC Generation - PHP
<?php
// Manual HMAC signature generation (if not using SDK)
function generateHmacSignature($apiSecret, $method, $path, $timestamp, $body) {
    // Create signature base string: METHOD|PATH|TIMESTAMP|BODY
    $signatureString = sprintf(
        "%s|%s|%s|%s",
        strtoupper($method),
        ltrim($path, '/'),  // Remove leading slash
        $timestamp,
        $body
    );

    // Generate HMAC SHA256 signature
    $signature = hash_hmac('sha256', $signatureString, $apiSecret);

    return $signature;
}

// Usage Example
$apiKey = 'your_api_key_here';
$apiSecret = 'your_api_secret_here';
$method = 'POST';
$path = '/api/v1/transaction/create';
$timestamp = time();
$nonce = bin2hex(random_bytes(16));

$requestData = [
    'amount' => 100.00,
    'currency' => 'USD',
    'redirectUrl' => 'https://yoursite.com/success'
];
$body = json_encode($requestData);

$signature = generateHmacSignature(
    $apiSecret,
    $method,
    $path,
    $timestamp,
    $body
);

// Make API request with HMAC headers
$ch = curl_init('https://api.epayse.com' . $path);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key-Id: ' . $apiKey,
        'X-Signature: ' . $signature,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

JavaScript/Node.js Example

JavaScript
Manual HMAC Generation - JavaScript
// Manual HMAC signature generation in JavaScript/Node.js
import crypto from 'crypto';

function generateHmacSignature(apiSecret, method, path, timestamp, body) {
    // Create signature string: METHOD|PATH|TIMESTAMP|BODY
    const signatureString = [
        method.toUpperCase(),
        path.replace(/^//, ''),  // Remove leading slash
        timestamp.toString(),
        body
    ].join('|');

    // Generate HMAC SHA256 signature
    const signature = crypto
        .createHmac('sha256', apiSecret)
        .update(signatureString)
        .digest('hex');

    return signature;
}

// Usage Example
const apiKey = 'your_api_key_here';
const apiSecret = 'your_api_secret_here';
const method = 'POST';
const path = '/api/v1/transaction/create';
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(16).toString('hex');

const requestData = {
    amount: 100.00,
    currency: 'USD',
    redirectUrl: 'https://yoursite.com/success'
};
const body = JSON.stringify(requestData);

const signature = generateHmacSignature(
    apiSecret,
    method,
    path,
    timestamp,
    body
);

// Make API request with HMAC headers
const response = await fetch('https://api.epayse.com' + path, {
    method: method,
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key-Id': apiKey,
        'X-Signature': signature,
        'X-Timestamp': timestamp.toString(),
        'X-Nonce': nonce,
    },
    body: body
});

const result = await response.json();
console.log(result);

Important Security Notes

⏰
Timestamp Validation: Requests with timestamps older than 5 minutes will be rejected to prevent replay attacks.
🔢
Nonce Uniqueness: Each nonce can only be used once. Reusing a nonce will result in request rejection.
🔐
Path Format: The path in signature generation should NOT include the leading slash (e.g., use api/v1/currencies not /api/v1/currencies).
📝
Body Format: For GET requests, use an empty string for the body in signature generation. For POST/PUT requests, use the exact JSON string (no formatting).

Security Best Practices

Use HTTPS Only

Always use HTTPS for API requests. Never send API keys over unencrypted connections.

Rotate Keys Regularly

Rotate your API keys every 90 days and immediately if you suspect they've been compromised.

Don't Expose Keys

Never commit API keys to version control or expose them in client-side code.

Don't Reuse Nonces

Always generate a unique nonce for each request to prevent replay attacks.

Next Steps

Now that you understand authentication, let's create your first transaction.