Authentication

EFICYENT APIs use a hybrid authentication mechanism that combines:

• Merchant Identification & API Key–based identification
• HMAC-SHA256 hashing
• RSA Private Key Signature
• Timestamp & Nonce for replay protection

This ensures high-grade security, request integrity, and protection against tampering or replay attacks.

How Authentication Works

Every outgoing API request must include the following headers:

Endpoints Excluded from Signature Validation

The following APIs do not require request signing:

• Registration
• Login

Signature Generation Flow

The client must generate a digital signature for every request using this process:

1. Add Merchant ID Header

• X-Merchant-Id is sent with every request.

2. Construct the URL Path

Extract only the last segment of the URL path.

Example:

/v1/payments/create → /create

3. Collect Request Data

Depending on the HTTP method:

• GET / DELETE → Convert all non-disabled query parameters into a JSON object.
• POST / PUT / PATCH→ Parse the raw JSON body or form-data (excluding files).

This becomes your request body object (bodyObj).

4. Generate the Plain Text String

Concatenate the following:

urlPath + JSON.stringify(bodyObj) + timestamp + saltKey

Example:

/create{"amount":1000,"currency":"USD"}1730001123mySaltKey123

5. Generate HMAC (SHA-256)

Use the salt_key as the secret to create an HMAC-SHA256 hash of the plain text.

HMAC = HMAC_SHA256(plainText, salt_key)

This HMAC ensures integrity of the request data.

6. RSA Private Key Signing

The generated HMAC hash is then signed using the merchant's RSA Private Key (PKCS#8).

Signature = RSA-SHA256-Sign(HMAC)

The signature is then encoded in Base64 and passed as the X-Api-Signature header.

7. Generate Nonce

• A random UUID to prevent replay attacks

8. Attach Headers

• Add all authentication headers to the request

Final Headers to Include

Each API request must include the following:

X-Merchant-Id: <merchant_id>
X-Api-Key: <api_key>
X-Api-Timestamp: <unix_timestamp>
X-Api-Signature: <rsa_signed_hmac_base64>
X-Api-Nonce: <uuid>

Security Benefits

This multi-step approach ensures every request is authenticated, validated, and tamper-proof.