Authentication

Learn how to authenticate your API requests with Gafiapay's secure authentication system using API keys and HMAC signatures.

Required Headers

All API requests must include the following headers for authentication:

Business Verification Requirements

Signature Generation

The signature is generated using HMAC SHA-256 with your secret key. The signature string is created by concatenating the request body (as a JSON string) and the timestamp.

const crypto = require('crypto');

function generateSignature(requestBody, timestamp, secretKey) {
  const signatureString = `${JSON.stringify(requestBody)}${timestamp}`;
  return crypto
    .createHmac('sha256', secretKey)
    .update(signatureString)
    .digest('hex');
}

// Example usage
const requestBody = {
  name: "John Doe",
  email: "john@example.com"
};
const timestamp = Date.now();
const signature = generateSignature(requestBody, timestamp, 'your_secret_key');

// Headers for the request
const headers = {
  'x-api-key': 'your_api_key',
  'x-signature': signature,
  'x-timestamp': timestamp,
  'Content-Type': 'application/json'
};

import hmac
import hashlib
import json
import time

def generate_signature(request_body, timestamp, secret_key):
    signature_string = f"{json.dumps(request_body)}{timestamp}"
    return hmac.new(
        secret_key.encode('utf-8'),
        signature_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

# Example usage
request_body = {
    "name": "John Doe",
    "email": "john@example.com"
}
timestamp = int(time.time() * 1000)
signature = generate_signature(request_body, timestamp, "your_secret_key")

# Headers for the request
headers = {
    'x-api-key': 'your_api_key',
    'x-signature': signature,
    'x-timestamp': str(timestamp),
    'Content-Type': 'application/json'
}

<?php

function generateSignature($requestBody, $timestamp, $secretKey) {
    $signatureString = json_encode($requestBody) . $timestamp;
    return hash_hmac('sha256', $signatureString, $secretKey);
}

// Example usage
$requestBody = [
    'name' => 'John Doe',
    'email' => 'john@example.com'
];
$timestamp = round(microtime(true) * 1000);
$signature = generateSignature($requestBody, $timestamp, 'your_secret_key');

// Headers for the request
$headers = [
    'x-api-key: your_api_key',
    'x-signature: ' . $signature,
    'x-timestamp: ' . $timestamp,
    'Content-Type: application/json'
];

require 'openssl'
require 'json'

def generate_signature(request_body, timestamp, secret_key)
  signature_string = request_body.to_json + timestamp.to_s
  OpenSSL::HMAC.hexdigest('sha256', secret_key, signature_string)
end

# Example usage
request_body = {
  name: 'John Doe',
  email: 'john@example.com'
}
timestamp = (Time.now.to_f * 1000).to_i
signature = generate_signature(request_body, timestamp, 'your_secret_key')

# Headers for the request
headers = {
  'x-api-key' => 'your_api_key',
  'x-signature' => signature,
  'x-timestamp' => timestamp.to_s,
  'Content-Type' => 'application/json'
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class SignatureGenerator {
    public static String generateSignature(Object requestBody, long timestamp, String secretKey) 
            throws NoSuchAlgorithmException, InvalidKeyException {
        ObjectMapper mapper = new ObjectMapper();
        String signatureString = mapper.writeValueAsString(requestBody) + timestamp;
        
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(
            secretKey.getBytes(StandardCharsets.UTF_8), 
            "HmacSHA256"
        );
        sha256Hmac.init(secretKeySpec);
        
        byte[] signedBytes = sha256Hmac.doFinal(
            signatureString.getBytes(StandardCharsets.UTF_8)
        );
        
        return bytesToHex(signedBytes);
    }
    
    private static String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }
    
    // Example usage
    public static void main(String[] args) throws Exception {
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("name", "John Doe");
        requestBody.put("email", "john@example.com");
        
        long timestamp = System.currentTimeMillis();
        String signature = generateSignature(requestBody, timestamp, "your_secret_key");
        
        // Headers for the request
        Map<String, String> headers = new HashMap<>();
        headers.put("x-api-key", "your_api_key");
        headers.put("x-signature", signature);
        headers.put("x-timestamp", String.valueOf(timestamp));
        headers.put("Content-Type", "application/json");
    }
}

Security Requirements

Error Responses

{
  "status": "fail",
  "message": "Missing required header: x-api-key"
}

{
  "status": "fail",
  "message": "Invalid API key"
}

{
  "status": "fail",
  "message": "Business not verified"
}

{
  "status": "fail",
  "message": "Request timestamp expired"
}

{
  "status": "fail",
  "message": "Invalid signature"
}

Example Request

curl -X POST 'https://api.gafiapay.com/api/v1/external/account/generate' \
  -H 'x-api-key: your_api_key' \
  -H 'x-signature: generated_signature' \
  -H 'x-timestamp: 1678901234567' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'

Success Response Format

All successful API responses follow this format:

{
  "status": "success",
  "data": {
    // Response data specific to the endpoint
  }
}

Error Response Format

All error responses follow this format:

{
  "status": "fail",
  "message": "Error description",
  "error": {
    "statusCode": 400,
    "name": "AppError",
    "stack": "Error stack trace (development only)"
  }
}