API Security Implementation Guide

Introduction

This document describes the security measures required to interact with our API endpoints. All requests must be encrypted and signed using the provided authentication credentials.

Authentication Credentials

Upon registration, you will receive:

Merchant-ID: A unique UUID that identifies your organization

Secret Key: A secret key used for encryption and signing

Request Security Requirements

Headers

Each request must include the following headers:

Merchant-ID: Your unique merchant identifier

X-HMAC: HMAC signature of the encrypted payload

Request Body

The request body should contain a single field:

encrypted_payload: The encrypted and base64-encoded payload

Encryption Process

1. Prepare the Request Payload

First, prepare your request data as a JSON object. For example:

{
    "email": "user@example.com",
    "mobileNumber": "1234567890",
    "mobilePrefix": "+1"
}

2. Encrypt the Payload

The payload must be encrypted using AES-CBC with PKCS7 padding:

Convert your JSON payload to a string

Generate a random 16-byte IV (Initialization Vector)

Encrypt the data using:

Algorithm: AES-CBC

Key: Your provided Secret Key

Padding: PKCS7

Concatenate the IV and encrypted data

Base64 encode the result

3. Generate HMAC

Calculate HMAC-SHA256 of the base64-encoded encrypted payload using your Secret Key

Convert the HMAC to hexadecimal format

Example Implementation (Python)

Response Format

The API response will follow the same security pattern:

{
    "encrypted_payload": "base64-encoded-encrypted-data",
    "hmac": "hmac-signature-of-encrypted-payload"
}

To decrypt the response:

Verify the HMAC signature

Base64 decode the encrypted payload

Extract the IV (first 16 bytes)

Decrypt the remaining data using AES-CBC

Remove PKCS7 padding

Parse the resulting JSON

Error Handling

The API will return HTTP 400 status code if:

The HMAC signature is invalid

The encrypted payload is malformed

The decrypted data is not valid JSON

The Merchant-ID is invalid

Security Recommendations

Never share your Secret Key

Generate a new IV for each request

Verify HMAC signatures for all responses

Use secure random number generation for IVs

Store the Secret Key securely

Use HTTPS for all API communications

API Security Implementation Guide

Introduction#

Authentication Credentials#

Request Security Requirements#

Headers#

Request Body#

Encryption Process#

1. Prepare the Request Payload#

2. Encrypt the Payload#

3. Generate HMAC#

Example Implementation (Python)#

Response Format#

Error Handling#

Security Recommendations#