🔒 Authentication

Security is paramount at IMB Payments. To safeguard every transaction and ensure only authorized applications access our APIs, we use header-based authentication.

How Authentication Works

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

Header Name	Type	Required	Description	Example
x-client-id	String	Yes	Your unique Client ID assigned via dashboard	`x-client-id: abc123xyz`
x-client-secret	String	Yes	Your secret key associated with the Client ID	`x-client-secret: s3cr3tK3y!`
Content-Type	String	Yes	Payload format header	`application/json`

Authentication Failure (401 Unauthorized)

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

HTTP/1.1 401 Unauthorized

{
  "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"
  }
}

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.

HTTP/1.1 403 Forbidden

{
  "response_code": 403,
  "error_code": "INVALID_IP",
  "message": "IP is not whitelisted.",
  "error": [],
  "data": null
}