Technical Guide

​

Overview

​

Data Types

​

Core Data Types

​

Data Length

​

Custom Properties

​

Amount

​

Idempotency

​

How Idempotency Works

1. Unique Key Generation: Generate a unique idempotency key for each transaction
2. Request Header: Include the idempotency key in the request headers
3. Server Processing: The server checks if the key has been used before
4. Response Handling:
   • First Request: Process normally and return response
   • Duplicate Request: Return the original response without processing again

​

Idempotency Key Requirements

• Uniqueness: Each key must be unique across all transactions
• Format: String format, typically UUID or timestamp-based
• Length: Maximum 255 characters
• Persistence: Keys are stored for a configurable period (typically 24-48 hours)

        curl -X GET ${AUTH_BASE_URL}/accounts \
          -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
          -H "signature: xxxxx-xxxxx-xxxx-xxxx"

​

Calculating Signature

​

Signature Formula

SHA-256(CLIENT_SECRET + ";" + idempotency_key_header)

​

How to Calculate

1. Concatenate: Combine your CLIENT_SECRET with a semicolon (;) and the idempotency_key_header
2. Hash: Apply SHA-256 hashing algorithm to the concatenated string
3. Result: The resulting hash is your request signature

// Example signature calculation
const clientSecret = "your_client_secret_here";
const idempotencyKey = "unique_request_id_123";
const signatureInput = clientSecret + ";" + idempotencyKey;
const signature = sha256(signatureInput);

// example signature calculation
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;

public class SignatureCalculator {


    static String computeSignature(String clientSecret, String idempotencyKey) throws Exception {
        String toSign = clientSecret + ";" + idempotencyKey;

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(toSign.getBytes(StandardCharsets.UTF_8));

        return Base64.getEncoder().encodeToString(hash);
    }
    
    // Usage example
    public static void main(String[] args) {
        String clientSecret = "your_client_secret_here";
        String idempotencyKey = "unique_request_id_123";
        String signature = calculateSignature(clientSecret, idempotencyKey);
        System.out.println("Signature: " + signature);
    }
}

​

URLS

        curl -X GET ${AUTH_BASE_URL}/accounts \
          -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
          -H "signature: xxxxx-xxxxx-xxxx-xxxx"

​

Best Practices

​

Data Validation

• Always validate data types before processing API responses
• Handle null/undefined values gracefully
• Use appropriate data type conversions when needed

​

Date Handling

• Always use Lagos West Africa timezone (WAT) for consistency
• Parse dates using ISO8601 standard libraries
• Consider timezone differences in your application

​

Number Precision

• Respect the 4 decimal place limit for monetary values
• Use appropriate decimal precision for calculations
• Avoid floating-point arithmetic for financial calculations

​

String Encoding

• Ensure UTF-8 encoding for all string data
• Handle special characters and emojis properly
• Validate string length limits where applicable