Bill Payment API Documentation | NICTBD.COM

Overview

NICTBD.COM Bill Payment API allows approved merchants to fetch providers, fetch services, submit bill payment requests and check latest order status using secure API credentials. Provider and service logo URLs are returned as full public URLs for easy frontend display.

This API is server-to-server only. Always call this API from your secure backend. Do not expose your API Secret in browser JavaScript, Android APK, iOS app, Flutter app, React Native app or public Git repository.

Core Features

Provider Check Get active bill providers with name, status and full logo URL.

Service Check Get active services under a provider with required module fields.

Dynamic Fields Each service can return custom module fields required for bill submit.

Bill Submit Submit bill payment request with provider, service, amount and required customer data.

Wallet Balance Merchant wallet balance is used for submitted bill payment requests.

Status Check Merchants can check latest bill payment status anytime using order number.

Verified Merchant Only Only approved merchants with active API credentials can use this API.

Secure API Access Every request requires Store ID, API Key and API Secret verification.

API Flow

1. Check Providers Merchant fetches active bill providers using the provider_check action.

2. Check Services Merchant fetches services and required module fields using provider ID.

3. Submit & Verify Merchant submits bill request and checks latest status using order number.

After submit, response status can be Processing. Use the status check API to get the latest result before confirming final bill payment status to your customer.

API Credentials

Merchant can collect API credentials from NICTBD.COM Merchant Dashboard after approval.

Credential	Required	Example	Usage
store_id	Required	`STORE-2-FRXECLKM`	Identifies your merchant store.
api_key	Required	`pk_live_xxxxxxxxx`	Merchant API key.
api_secret	Required	`sk_live_xxxxxxxxx`	Private API secret. Keep it hidden and secure.

Merchant verification status must be approved. Inactive or unapproved merchants cannot use this API.

API Endpoint

Use the same endpoint with different action query values.

POST https://www.nictbd.com/api/bill-payment?action=provider_check

POST https://www.nictbd.com/api/bill-payment?action=service_check

POST https://www.nictbd.com/api/bill-payment?action=submit

POST https://www.nictbd.com/api/bill-payment?action=status_check

Headers

Accept: application/json
Content-Type: application/x-www-form-urlencoded

JSON request body is also supported if your backend sends Content-Type: application/json.

API Actions

Action	Method	Purpose	Required Main Fields
`provider_check`	POST	Get active bill providers.	`store_id`, `api_key`, `api_secret`
`service_check`	POST	Get services under selected provider.	`store_id`, `api_key`, `api_secret`, `provider_id`
`submit`	POST	Submit bill payment request.	`store_id`, `api_key`, `api_secret`, `provider_id`, `service_id`, `amount`
`status_check`	POST	Check latest order status.	`store_id`, `api_key`, `api_secret`, `order_number`

Module Fields

Each service can require different information from the customer. The service_check response includes module_fields. Merchant must send those fields during submit.

Example Module Fields

{
  "module_name": "customer_number,bill_month",
  "module_fields": [
    "customer_number",
    "bill_month"
  ]
}

Bill Month Format

If a service requires bill_month, merchant can send it directly or send month and year separately.

Direct Bill Month

bill_month=January-2026

Month + Year

bill_month_month=January
bill_month_year=2026

Integration Examples

Swipe tabs horizontally to view more examples.

cURL Examples

Provider Check

curl -X POST "https://www.nictbd.com/api/bill-payment?action=provider_check" \
  -H "Accept: application/json" \
  -d "store_id=YOUR_STORE_ID" \
  -d "api_key=YOUR_API_KEY" \
  -d "api_secret=YOUR_API_SECRET"

Service Check

curl -X POST "https://www.nictbd.com/api/bill-payment?action=service_check" \
  -H "Accept: application/json" \
  -d "store_id=YOUR_STORE_ID" \
  -d "api_key=YOUR_API_KEY" \
  -d "api_secret=YOUR_API_SECRET" \
  -d "provider_id=1"

Submit Bill Payment

curl -X POST "https://www.nictbd.com/api/bill-payment?action=submit" \
  -H "Accept: application/json" \
  -d "store_id=YOUR_STORE_ID" \
  -d "api_key=YOUR_API_KEY" \
  -d "api_secret=YOUR_API_SECRET" \
  -d "provider_id=1" \
  -d "service_id=2" \
  -d "amount=500" \
  -d "customer_number=123456789" \
  -d "bill_month=January-2026"

Status Check

curl -X POST "https://www.nictbd.com/api/bill-payment?action=status_check" \
  -H "Accept: application/json" \
  -d "store_id=YOUR_STORE_ID" \
  -d "api_key=YOUR_API_KEY" \
  -d "api_secret=YOUR_API_SECRET" \
  -d "order_number=NICT-ABC123XYZ789"

PHP cURL Example

PHP

<?php

$url = 'https://www.nictbd.com/api/bill-payment?action=submit';

$data = [
    'store_id' => 'YOUR_STORE_ID',
    'api_key' => 'YOUR_API_KEY',
    'api_secret' => 'YOUR_API_SECRET',
    'provider_id' => '1',
    'service_id' => '2',
    'amount' => '500',
    'customer_number' => '123456789',
    'bill_month' => 'January-2026',
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$error = curl_error($ch);
curl_close($ch);

if ($error) {
    echo 'Curl Error: ' . $error;
    exit;
}

$result = json_decode($response, true);

if (!empty($result['success']) && $result['success'] === true) {
    echo 'Bill Payment Request Submitted. Order: ' . $result['order_number'];
} else {
    echo 'Request Failed. Reason: ' . ($result['error'] ?? 'Unknown error');
}

print_r($result);

Laravel HTTP Client Example

Laravel

use Illuminate\Support\Facades\Http;

$response = Http::asForm()
    ->acceptJson()
    ->timeout(60)
    ->post('https://www.nictbd.com/api/bill-payment?action=submit', [
        'store_id' => config('services.nictbd.store_id'),
        'api_key' => config('services.nictbd.api_key'),
        'api_secret' => config('services.nictbd.api_secret'),
        'provider_id' => 1,
        'service_id' => 2,
        'amount' => '500',
        'customer_number' => '123456789',
        'bill_month' => 'January-2026',
    ]);

$result = $response->json();

if (($result['success'] ?? false) === true) {
    // Request submitted
    // Save order_number and check status later
} else {
    // Request failed
    // Show $result['error']
}

Node.js Example

Node.js

const payload = new URLSearchParams({
  store_id: "YOUR_STORE_ID",
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET",
  provider_id: "1",
  service_id: "2",
  amount: "500",
  customer_number: "123456789",
  bill_month: "January-2026"
});

const response = await fetch("https://www.nictbd.com/api/bill-payment?action=submit", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: payload
});

const result = await response.json();

if (result.success === true) {
  console.log("Request Submitted:", result.order_number);
} else {
  console.log("Request Failed:", result.error);
}

Python Example

Python

import requests

payload = {
    "store_id": "YOUR_STORE_ID",
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET",
    "provider_id": "1",
    "service_id": "2",
    "amount": "500",
    "customer_number": "123456789",
    "bill_month": "January-2026"
}

response = requests.post(
    "https://www.nictbd.com/api/bill-payment?action=submit",
    data=payload,
    headers={"Accept": "application/json"},
    timeout=60
)

result = response.json()

if result.get("success") is True:
    print("Request Submitted:", result.get("order_number"))
else:
    print("Request Failed:", result.get("error"))

Provider Check Response

Use action=provider_check to get active bill providers.

Request Parameters

Field	Required	Example	Description
store_id	Required	`STORE-2-FRXECLKM`	Your Store ID.
api_key	Required	`pk_live_xxxxxxxxx`	Your API Key.
api_secret	Required	`sk_live_xxxxxxxxx`	Your API Secret.

Success Response

JSON Response

{
  "success": true,
  "providers": [
    {
      "id": "1",
      "name": "DESCO",
      "logo": "https://www.nictbd.com/uploads/logo/desco.png",
      "status": "active"
    }
  ]
}

Service Check Response

Use action=service_check with provider_id to get services and required module fields.

Request Parameters

Field	Required	Example	Description
store_id	Required	`STORE-2-FRXECLKM`	Your Store ID.
api_key	Required	`pk_live_xxxxxxxxx`	Your API Key.
api_secret	Required	`sk_live_xxxxxxxxx`	Your API Secret.
provider_id	Required	`1`	Provider ID from provider_check response.

Success Response

JSON Response

{
  "success": true,
  "provider": {
    "id": "1",
    "name": "DESCO",
    "logo": "https://www.nictbd.com/uploads/logo/desco.png"
  },
  "services": [
    {
      "id": "2",
      "provider_id": "1",
      "name": "Prepaid Meter Recharge",
      "logo": "https://www.nictbd.com/uploads/logo/desco-prepaid.png",
      "module_name": "meter_number,bill_month",
      "module_fields": [
        "meter_number",
        "bill_month"
      ]
    }
  ]
}

Submit Bill Payment Response

Use action=submit with provider, service, amount and required module fields. A successful submit response means the request has been accepted for processing.

Request Parameters

Field	Required	Example	Description
store_id	Required	`STORE-2-FRXECLKM`	Your Store ID.
api_key	Required	`pk_live_xxxxxxxxx`	Your API Key.
api_secret	Required	`sk_live_xxxxxxxxx`	Your API Secret.
provider_id	Required	`1`	Provider ID.
service_id	Required	`2`	Service ID.
amount	Required	`500`	Bill payment amount.
module fields	Required	`meter_number`	Required fields from service_check response.
bill_month	Conditional	`January-2026`	Required only if service module fields include bill_month.

Success Response

JSON Response

{
  "success": true,
  "order_number": "NICT-ABC123XYZ789",
  "status": "Processing",
  "provider": "DESCO",
  "service": "Prepaid Meter Recharge",
  "provider_logo": "https://www.nictbd.com/uploads/logo/desco.png",
  "service_logo": "https://www.nictbd.com/uploads/logo/desco-prepaid.png",
  "module_data": {
    "meter_number": "123456789"
  },
  "bill_month": "January-2026",
  "amount": "500.00",
  "debit_amount": "500.00",
  "total_amount": "500.00",
  "before_balance": "1500.00",
  "after_balance": "1000.00"
}

Merchant should save the order_number and use status check API to get final order result.

Status Check Response

Use action=status_check with order_number to check latest bill payment status.

Request Parameters

Field	Required	Example	Description
store_id	Required	`STORE-2-FRXECLKM`	Your Store ID.
api_key	Required	`pk_live_xxxxxxxxx`	Your API Key.
api_secret	Required	`sk_live_xxxxxxxxx`	Your API Secret.
order_number	Required	`NICT-ABC123XYZ789`	Order number from submit response.

Processing Response

JSON Response

{
  "success": true,
  "order_number": "NICT-ABC123XYZ789",
  "status": "Processing",
  "provider": "DESCO",
  "service": "Prepaid Meter Recharge",
  "provider_logo": "https://www.nictbd.com/uploads/logo/desco.png",
  "service_logo": "https://www.nictbd.com/uploads/logo/desco-prepaid.png",
  "module_data": {
    "meter_number": "123456789"
  },
  "bill_month": "January-2026",
  "amount": "500.00",
  "debit_amount": "500.00",
  "total_amount": "500.00",
  "response": "Bill payment request submitted"
}

Success Response

JSON Response

{
  "success": true,
  "order_number": "NICT-ABC123XYZ789",
  "status": "Success",
  "provider": "DESCO",
  "service": "Prepaid Meter Recharge",
  "module_data": {
    "meter_number": "123456789"
  },
  "bill_month": "January-2026",
  "amount": "500.00",
  "debit_amount": "500.00",
  "total_amount": "500.00",
  "token_number": "TOKEN123456789"
}

Cancelled Response

JSON Response

{
  "success": true,
  "order_number": "NICT-ABC123XYZ789",
  "status": "Cancelled",
  "provider": "DESCO",
  "service": "Prepaid Meter Recharge",
  "module_data": {
    "meter_number": "123456789"
  },
  "bill_month": "January-2026",
  "amount": "500.00",
  "debit_amount": "500.00",
  "total_amount": "500.00",
  "cancel_note": "Request could not be completed."
}

Error Responses

Missing API Credentials

JSON

{
  "success": false,
  "error": "Missing API credentials."
}

Invalid API Credentials

JSON

{
  "success": false,
  "error": "Invalid API credentials."
}

Merchant Verification Not Approved

JSON

{
  "success": false,
  "error": "Merchant verification is not approved."
}

Invalid Provider ID

JSON

{
  "success": false,
  "error": "Invalid provider ID."
}

Invalid Service Or Provider

JSON

{
  "success": false,
  "error": "Invalid service or provider."
}

Missing Module Data

JSON

{
  "success": false,
  "error": "Missing required module data."
}

Missing Bill Month

JSON

{
  "success": false,
  "error": "Missing bill_month."
}

Insufficient Balance

JSON

{
  "success": false,
  "error": "Insufficient balance."
}

Transaction Not Found

JSON

{
  "success": false,
  "error": "Transaction not found."
}

Security Guidelines

Call Bill Payment API only from your backend server.
Never expose api_secret in frontend JavaScript, mobile app source code or public repository.
Keep credentials inside environment variables or secure configuration.
Use service_check response to collect required module fields before submit.
Use order_number from submit response to check final status.
Do not show final success to customer until status check returns Success.
Contact support immediately if API Secret is leaked.

If your API Secret is compromised, regenerate credentials from merchant dashboard or contact NICTBD.COM support.

Important Notes

Topic	Explanation
Merchant Approval	Only approved merchants can use Bill Payment API.
Provider Check	Use `provider_check` action to get latest provider list.
Service Check	Use `service_check` action to get services and required module fields.
Submit Action	Use `submit` action to submit bill payment request.
Status Check	Use `status_check` action to check latest order status.
Logo URL	Provider and service logo are returned as full public URLs.
Final Status	Final result should be confirmed using status check API.
API Security	Always keep `api_secret` private and call this API from backend only.

For API support, please contact NICTBD.COM support team with your Store ID and order number.

NICTBD.COM Bill Payment API Documentation

Overview

Core Features

API Flow

API Credentials

API Endpoint

Headers

API Actions

Module Fields

Bill Month Format

Integration Examples

cURL Examples

PHP cURL Example

Laravel HTTP Client Example

Node.js Example

Python Example

Provider Check Response

Request Parameters

Success Response

Service Check Response

Request Parameters

Success Response

Submit Bill Payment Response

Request Parameters

Success Response

Status Check Response

Request Parameters

Processing Response

Success Response

Cancelled Response

Error Responses

Missing API Credentials

Invalid API Credentials

Merchant Verification Not Approved

Invalid Provider ID

Invalid Service Or Provider

Missing Module Data

Missing Bill Month

Insufficient Balance

Transaction Not Found

Security Guidelines

Important Notes