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.
Core Features
Recharge Flow
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. |
approved. Pending, submitted or rejected merchants
cannot use the recharge API.
Recharge API Endpoint
Use this endpoint to submit a mobile recharge request.
https://www.nictbd.com/api/recharge
Headers
Accept: application/json Content-Type: application/x-www-form-urlencoded
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=GP cannot be used for a Robi number.
Integration Examples
cURL Example
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
$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
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
}
.env file and never commit them to GitHub.
Node.js Example
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
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.
{
"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.
{
"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 |
success: true. Any success: false response should be handled as failed.
Error Responses
Insufficient Balance
{
"success": false,
"error": "Insufficient balance."
}
Invalid API Credentials
{
"success": false,
"error": "Invalid API credentials."
}
Merchant Verification Not Approved
{
"success": false,
"error": "Merchant verification is not approved."
}
Invalid Operator
{
"success": false,
"error": "Invalid operator.",
"allowed_operator": ["GP", "GP ST", "BL", "RB", "AT", "TT"]
}
Invalid Operator Number
{
"success": false,
"error": "Invalid operator number for this recharge."
}
Service Temporarily Unavailable
{
"success": false,
"error": "Something went wrong. Please try again later."
}
Security Guidelines
- Always call recharge API from your backend server.
- Never expose
api_secretin 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 === truebefore showing recharge successful. - Store
order_numberandoperator_transaction_idin your own system if needed. - Do not retry the same recharge repeatedly without checking the previous response.
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. |