Authentication

🔒 Authentication

Security is paramount at IMB Payments. To safeguard every transaction and ensure only authorized applications access our APIs, we use header-based authentication. This method requires every API request to include your unique credentials securely in the HTTP headers.

How Authentication Works

Every request to IMB Payments APIs must include two mandatory headers:

Header Name	Description	Example
`x-client-id`	Your unique Client ID assigned via dashboard	`client-id: abc123xyz`
`x-client-secret`	Your secret key associated with the Client ID	`client-secret: s3cr3tK3y!`

Requests without these headers or with invalid credentials will be rejected with an appropriate HTTP 401 Unauthorized response.

Example Request Structure

client-id: {YOUR_CLIENT_ID}
client-secret: {YOUR_CLIENT_SECRET}
Content-Type: application/json

What Happens if Authentication Fails?

When invalid or missing authentication headers are detected, IMB Payments responds with:

{
    "response_code": 401,
    "error_code": "INVALID_CREDENTIALS",
    "message": "Missing API credentials client id & client secret.",
    "error": [],
    "data": null,
    "meta": {
        "request_id": "f0ca3884-24da-43df-9c5b-106b9d3e23c4",
        "time": "2025-08-30T16:05:17+05:30"
    }
}

This response indicates that the request was blocked because the credentials were incorrect or absent. Review and verify your headers to avoid disruptions.

Important Security Best Practices

WARNING

Never expose your x-client-id or x-client-secret in client-side applications (such as JavaScript running in browsers or mobile apps). These credentials must always remain confidential.

Treat your x-client-secret like a password. If you suspect it has been compromised, immediately regenerate it from your dashboard.

Only send API requests over HTTPS to protect credentials from interception.

Implement secure storage and access control for your credentials within your backend systems.

What is IP Whitelisting?

IP whitelisting (also called allowlisting) is an additional security measure that restricts API access to requests originating only from IP addresses or IP ranges that you explicitly authorize.

When enabled, API calls from non-whitelisted IPs will be blocked with a 403 Forbidden response, adding another layer of protection against unauthorized or malicious access.

How to Enable IP Whitelisting

You can configure your IP whitelist securely via your IMB Payments Dashboard under the API Security or Developer Controls section.

Whitelist individual IP addresses or CIDR ranges that represent your trusted servers or networks.

You can update this list anytime; however, changes may require regeneration of API tokens or keys depending on your security settings.

Example IP Whitelist Use Case

Suppose your backend servers have static IPs 203.0.113.4 and 203.0.113.5. You add these to your IP whitelist. Now only requests from these IPs succeed; all others result in:

{
    "response_code": 403,
    "error_code": "INVALID_IP",
    "message": "IP is not whitelisted.",
    "error": [],
    "data": null,
    "meta": {
        "request_id": "10828ca0-7b8d-422a-bfee-0e648fd47dae",
        "time": "2025-08-30T16:27:03+05:30"
    }
}

Best Practices & Recommendations

WARNING

Never disable IP whitelisting on production APIs unless absolutely necessary.

Keep your whitelist up-to-date to include only trusted IPs.

Use IP whitelisting in combination with header-based authentication for maximum security.

If you use dynamic IPs, consider working with your network team or account manager to implement VPNs or static IP proxies.

Regularly audit your IP whitelist and API keys for compliance and security.

Summary

Authentication + IP whitelisting = multilayer protection of your API ecosystem, ensuring:

Only authorized users access your APIs.

Requests are made from trusted network locations.

Reduced risk of credential misuse or data breaches.

For assistance configuring IP whitelist or to learn about supported ranges, please contact IMB Payments support or visit the Merchant Dashboard.

Authentication

🔒 Authentication#

How Authentication Works#

Example Request Structure#

What Happens if Authentication Fails?#

Important Security Best Practices#

What is IP Whitelisting?#

How to Enable IP Whitelisting#

Example IP Whitelist Use Case#

Best Practices & Recommendations#

Summary#