curl -X POST https://api.imbpayment.com/v1/verification/upi-verify \
  -H "x-client-id: {{client_id}}" \
  -H "x-client-secret: {{client_secret}}" \
  -H "Content-Type: application/json" \
  -d '{
    "upi_id": "test1234@ybl"
  }'

Core Infrastructure Pillars

Getting Started

IMB Payments is an Indian leading API-first infrastructure provider. Our mission is to solve digital payments and verification challenges by offering a suite of modular, scalable, and developer-focused APIs.

🔒 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:

Authentication Failure (401 Unauthorized)

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

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.

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

🟢 HTTP Status Codes

Standardized HTTP response status codes returned by IMB Payment API services.

⏳ Rate Limits

To ensure fair usage and maintain optimal performance for all clients, IMB Payments enforces strict rate limits.

What Happens When You Exceed Limits?

{
  "error": true,
  "message": "Rate limit exceeded. Please try again after some time."
}

🧩 Key Features of IMB Payments APIs

The Recharge Callback API is used to send real-time recharge status updates to the merchant server once the transaction is processed by the operator. Instead of continuously polling the Status API, merchants should implement this webhook to receive automatic transaction updates.

When Callback Is Triggered

• Recharge Successful
• Recharge Failed
• Operator Final Status Update

SUCCESS RECHARGE WEBHOOK PAYLOAD

{
  "event": "RECHARGE_SUCCESS",
  "status": "success",
  "data": {
    "request_id": "rechtxn00001",
    "number": "99XXXXXX99",
    "amount": "22.00",
    "operator_id": "11",
    "reference_id": "IMBRCH22264720260227_f870fdf4",
    "ackno": "1122XXXX65",
    "message": "SUCCESS",
    "refunded": false
  },
  "timestamp": "2026-03-01T12:05:21+05:30"
}

FAILED RECHARGE WEBHOOK PAYLOAD

{
  "event": "RECHARGE_FAILURE",
  "status": "failed",
  "data": {
    "request_id": "rechtxn00001",
    "number": "99XXXXXX99",
    "amount": "22.00",
    "operator_id": "11",
    "reference_id": "IMBRCH22280520260227_8c5ef3a3",
    "ackno": "112XXXXX65",
    "message": "Failed",
    "refunded": true
  },
  "timestamp": "2026-03-01T12:12:08+05:30"
}

📥 Merchant Expected Response

After receiving the callback, merchant server must return HTTP 200 response within 3 seconds:

{
  "status": 200,
  "message": "Transaction completed successfully"
}

After an NSDL account opening request is processed, IMB Payment sends an automated HTTP POST callback to your registered webhook URL with the final status of the request.

Request Headers

Signature Verification

Always verify the X-Webhook-Signature header before processing the webhook payload. IMB Payment signs every webhook request using HMAC SHA-256 with your secret key.

const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(digest));
}

Supported Events

Event: NSDL_ACCOUNT_CREATED Payload Example

{
  "event": "NSDL_ACCOUNT_CREATED",
  "timestamp": "2025-06-28T10:30:00+05:30",
  "request_id": "REQ7834HDJK23",
  "data": {
    "request_id": "REQ7834HDJK23",
    "pancard": "ABCDE1234F",
    "customer_name": "Rajesh Kumar",
    "account_number": "9876543210123456",
    "ifsc_code": "NSDL0000001",
    "cif_number": "CIF123456789",
    "account_type": "Savings",
    "bank_name": "NSDL Payments Bank",
    "branch": "Mumbai Main Branch",
    "profile_pic": "https://example.com/profile/abc123.jpg",
    "customer_care": "1800-123-4567",
    "account_status": "success",
    "is_refunded": false,
    "is_completed": true
  }
}

Payload Field Explanation

API Reference Explorer

Interactive documentation, request parameters, response schemas, and code generators for all IMB Payment endpoints.

SDKs & Libraries

Official SDKs and integration wrappers maintained by the IMB Payment Engineering team.

Error Handling Standards

Standardized HTTP response error codes and recommended client handling strategies.