Topup API Documentation

NICTBD.COM Mobile Recharge API Documentation

Integrate NICTBD.COM mobile recharge API into your PHP website, Laravel application, ecommerce platform, mobile app backend or custom software. Verified merchants can recharge GP, Skitto, Banglalink, Robi, Airtel and Teletalk numbers using Store ID, API Key and Secret Key. The API returns clear JSON response with recharge status and wallet balance information.

Overview

NICTBD.COM Mobile Recharge API allows verified merchants to recharge Bangladeshi mobile numbers directly from their own backend system. The merchant wallet must have sufficient balance before a recharge request. After processing, API returns a JSON response with final status, operator information, amount and wallet balance details.

This API is server-to-server only. Use it from your backend PHP, Laravel, Node.js, Python or mobile app backend. Do not expose your API Secret in frontend JavaScript, Android APK, iOS app, Flutter app or public source code.

Core Features

Mobile Recharge Recharge GP, Skitto, Banglalink, Robi, Airtel and Teletalk numbers.
Wallet Balance Recharge request is processed using merchant wallet balance.
Verified Merchant Only Only approved merchants can use this API endpoint.
API Credentials Store ID, API Key and Secret Key are required for every request.
Commission Support Applicable commission is shown in successful recharge response.
Automatic Balance Adjustment If a recharge is not completed successfully, any deducted amount is returned to the merchant wallet.
Recharge History Merchants can review recharge status, amount, operator and balance information from their dashboard.
Secure API Processing All recharge requests are processed through secure merchant API authentication and validation.

Recharge Flow

1. Merchant API Call Merchant sends Store ID, API Key, Secret Key, operator, phone and amount.
2. Request Validation System verifies merchant approval, API credentials, operator, phone number and wallet balance.
3. API Response Merchant receives final JSON response with success or failed status and balance information.
If recharge is successful, the final response includes recharge details and updated balance. If recharge is not completed successfully, any deducted amount is returned to the merchant wallet automatically.

API Credentials

Merchant can find API credentials from NICTBD.COM Merchant Dashboard after account approval.

Credential Example Required Usage
store_id STORE-2-FRXECLKM Required Identifies your merchant store.
api_key pk_live_xxxxxxxxx Required Public API key used for authentication.
api_secret sk_live_xxxxxxxxx Required Private secret key. Never expose it publicly.
Merchant verification status must be approved. Pending, submitted or rejected merchants cannot use the recharge API.

Recharge API Endpoint

Use this endpoint to submit a mobile recharge request.

POST https://www.nictbd.com/api/recharge

Headers

Headers
Accept: application/json
Content-Type: application/x-www-form-urlencoded
JSON body can also be used if your system sends Content-Type: application/json. PHP cURL form-data is fully supported.

Request Parameters

Field Required Type Example Description
store_id Required string STORE-2-FRXECLKM Your NICTBD.COM merchant Store ID.
api_key Required string pk_live_xxxxxxxxx Your active merchant API key.
api_secret Required string sk_live_xxxxxxxxx Your private merchant API secret.
operator Required string GP Mobile operator code. Example: GP, BL, RB.
phone Required string 01700000000 Recharge mobile number. Bangladesh local format is recommended.
amount Required decimal 20 or 20.00 Recharge amount. Amount must follow allowed minimum and maximum limit.
account_type Optional string prepaid Allowed values: prepaid, postpaid. Default is prepaid.

Supported Operators

Operator Code Operator Name Allowed Number Prefix Example Number
GP Grameenphone 013, 017 01700000000
GP ST Grameenphone Skitto 013, 017 01300000000
BL Banglalink 014, 019 01900000000
RB Robi 018 01800000000
AT Airtel 016 01600000000
TT Teletalk 015 01500000000
Operator and number prefix must match. Example: operator=GP cannot be used for a Robi number.

Integration Examples

Swipe tabs horizontally to view more examples.

cURL Example

cURL
curl -X POST "https://www.nictbd.com/api/recharge" \
  -H "Accept: application/json" \
  -d "store_id=YOUR_STORE_ID" \
  -d "api_key=YOUR_API_KEY" \
  -d "api_secret=YOUR_API_SECRET" \
  -d "operator=GP" \
  -d "phone=01700000000" \
  -d "amount=20" \
  -d "account_type=prepaid"

PHP cURL Example

PHP
<?php

$url = 'https://www.nictbd.com/api/recharge';

$data = [
    'store_id' => 'YOUR_STORE_ID',
    'api_key' => 'YOUR_API_KEY',
    'api_secret' => 'YOUR_API_SECRET',
    'operator' => 'GP',
    'phone' => '01700000000',
    'amount' => '20',
    'account_type' => 'prepaid',
];

$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 'Recharge Success. Order: ' . $result['order_number'];
} else {
    echo 'Recharge Failed. Reason: ' . ($result['failure_reason'] ?? $result['error'] ?? 'Unknown error');

    if (!empty($result['refund']['success'])) {
        echo ' Refund Amount: ' . $result['refund']['refund_amount'];
    }
}

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/recharge', [
        'store_id' => config('services.nictbd.store_id'),
        'api_key' => config('services.nictbd.api_key'),
        'api_secret' => config('services.nictbd.api_secret'),
        'operator' => 'GP',
        'phone' => '01700000000',
        'amount' => '20',
        'account_type' => 'prepaid',
    ]);

$result = $response->json();

if (($result['success'] ?? false) === true) {
    // Recharge successful
    // Save order_number and operator_transaction_id if needed
} else {
    // Recharge failed
    // Show failure_reason or error message
}
Add credentials in your merchant system .env file and never commit them to GitHub.

Node.js Example

Node.js
const payload = new URLSearchParams({
  store_id: "YOUR_STORE_ID",
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET",
  operator: "GP",
  phone: "01700000000",
  amount: "20",
  account_type: "prepaid"
});

const response = await fetch("https://www.nictbd.com/api/recharge", {
  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("Recharge Success:", result.order_number);
} else {
  console.log("Recharge Failed:", result.failure_reason || result.error);
}

Python Example

Python
import requests

payload = {
    "store_id": "YOUR_STORE_ID",
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET",
    "operator": "GP",
    "phone": "01700000000",
    "amount": "20",
    "account_type": "prepaid"
}

response = requests.post(
    "https://www.nictbd.com/api/recharge",
    data=payload,
    headers={"Accept": "application/json"},
    timeout=60
)

result = response.json()

if result.get("success") is True:
    print("Recharge Success:", result.get("order_number"))
else:
    print("Recharge Failed:", result.get("failure_reason") or result.get("error"))

Success Response

If recharge is successful, API returns success: true. Merchant should treat recharge as successful only when success is exactly true.

JSON Response
{
  "success": true,
  "order_number": "NICT-A1B2C3D4E5F6",
  "merchant_id": 5,
  "phone": "01700000000",
  "amount": "20.00",
  "operator_code": "GP",
  "operator_name": "Grameenphone",
  "account_type": "prepaid",
  "commission_amount": "0.40",
  "before_balance": "500.00",
  "after_deduct_balance": "480.00",
  "after_balance": "480.40",
  "operator_transaction_id": "123456789",
  "status": "Success"
}

Balance Example

Step Amount Balance
Before recharge - 500.00
Recharge amount applied -20.00 480.00
Commission applied +0.40 480.40

Failed Recharge Response

If recharge is not completed successfully, API returns success: false. In this case, any deducted amount is returned to the merchant wallet automatically and the response includes the final wallet balance.

JSON Response
{
  "success": false,
  "order_number": "NICT-A1B2C3D4E5F6",
  "merchant_id": 5,
  "phone": "01700000000",
  "amount": "20.00",
  "operator_code": "GP",
  "operator_name": "Grameenphone",
  "account_type": "prepaid",
  "commission_amount": "0.00",
  "before_balance": "500.00",
  "after_deduct_balance": "480.00",
  "after_balance": "500.00",
  "operator_transaction_id": null,
  "status": "Failed",
  "refund": {
    "success": true,
    "status": "Refunded",
    "refund_amount": "20.00"
  },
  "failure_reason": "Recharge failed. Amount has been returned to merchant wallet."
}

Balance Example

Step Amount Balance
Before recharge - 500.00
Recharge amount applied -20.00 480.00
Amount returned +20.00 500.00
Merchant should treat recharge as successful only when the API response contains success: true. Any success: false response should be handled as failed.

Error Responses

Insufficient Balance

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

Invalid API Credentials

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

Merchant Verification Not Approved

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

Invalid Operator

JSON
{
  "success": false,
  "error": "Invalid operator.",
  "allowed_operator": ["GP", "GP ST", "BL", "RB", "AT", "TT"]
}

Invalid Operator Number

JSON
{
  "success": false,
  "error": "Invalid operator number for this recharge."
}

Service Temporarily Unavailable

JSON
{
  "success": false,
  "error": "Something went wrong. Please try again later."
}

Security Guidelines

  • Always call recharge API from your backend server.
  • Never expose api_secret in frontend JavaScript, mobile app source code or public repository.
  • Keep your Store ID, API Key and Secret Key in environment variables.
  • Validate customer phone number and operator before calling the API.
  • Always check success === true before showing recharge successful.
  • Store order_number and operator_transaction_id in your own system if needed.
  • Do not retry the same recharge repeatedly without checking the previous response.
If your Secret Key is leaked, immediately regenerate API credentials from merchant dashboard or contact NICTBD.COM support.

Important Notes

Topic Explanation
Merchant Approval Only merchants with verification status approved can call recharge API.
Wallet Balance Merchant wallet must have sufficient balance before recharge request.
Success Response Recharge is successful only when API response contains success: true.
Failed Response If recharge is not completed, API returns success: false with reason or error message.
Balance Adjustment If any amount is deducted for an unsuccessful recharge, it will be returned to the merchant wallet automatically.
API Security Always keep api_secret private and call this API from your secure backend server only.
For API support, please contact NICTBD.COM support team with your Store ID and recharge order number.