Special Offer: 10% Cash back offer
Sign Up Now

API Documentation

Welcome to iRecharge Pro API documentation. This guide will help you integrate mobile recharge and billing services into your application.

All API endpoints require authentication using API credentials (Open Key + Secret Key).

🧪

Sandbox Environment

Use for testing and development. Keys start with ok_test_* and sk_test_*

• Simulated transactions • No real charges • Perfect for integration testing

🚀

Production Environment

Use for live transactions. Keys start with ok_live_* and sk_live_*

• Real transactions • Actual charges • Production-ready

Authentication

All API requests must include your API credentials in the headers. You need both an Open Key and a Secret Key:

Required Headers

ok_test_XXXXXXXXXXXXXXXXXXXXXXXX

Your public API key (visible, used for routing)

sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Your secret API key (keep this secure, used for authentication)

curl -X GET https://demo.irecharge.net/api/billing/balance \
  -H "X-Open-Key: ok_test_YOUR_OPEN_KEY" \
  -H "X-Authorization: sk_test_YOUR_SECRET_KEY"

IP Whitelist (Optional)

For enhanced security, you can restrict API access to specific IP addresses or CIDR ranges from your Developer Dashboard.

• Add single IPs: 192.168.1.1

• Add CIDR ranges: 10.0.0.0/24

• Leave empty to allow all IPs

You can obtain your API credentials from the Developer Dashboard after signing up.

Base URL

All API endpoints use the following base URL:

https://demo.irecharge.net/api/billing

Note: The same API credentials work for both sandbox and production environments. The system automatically detects your environment based on your API key prefix (ok_test_* = Sandbox, ok_live_* = Production).

API Endpoints

Check Balance

Get your current wallet balance.

GET /api/billing/wallet/balance 
curl --location 'https://demo.irecharge.net/api/billing/wallet/balance' \
  --header 'X-Open-Key: ok_test_YOUR_OPEN_KEY' \
  --header 'X-Authorization: sk_test_YOUR_SECRET_KEY'

Response (200 OK):

{
  "balance": "7000.00",
  "currency": "BDT"
}

Get Available Operators

Retrieve a list of available mobile operators and services.

GET /api/billing/operators 
curl --location 'https://demo.irecharge.net/api/billing/operators' \
  --header 'X-Open-Key: ok_test_YOUR_OPEN_KEY' \
  --header 'X-Authorization: sk_test_YOUR_SECRET_KEY'

Response (200 OK):

[
  {
    "id": 1,
    "country_id": 1,
    "service_id": 1,
    "operator_code": "GP",
    "operator_name": "Grameenphone",
    "short_name": null,
    "description": null,
    "logo": "grameenphone.png",
    "is_active": true,
    "display_order": 0,
    "created_at": "2026-01-18T13:22:53.000000Z",
    "updated_at": "2026-01-18T13:22:53.000000Z"
  },
  {
    "id": 2,
    "country_id": 1,
    "service_id": 1,
    "operator_code": "BL",
    "operator_name": "Banglalink",
    "short_name": null,
    "description": null,
    "logo": "banglalink.png",
    "is_active": true,
    "display_order": 0,
    "created_at": "2026-01-18T13:22:53.000000Z",
    "updated_at": "2026-01-18T13:22:53.000000Z"
  },
  {
    "id": 3,
    "country_id": 1,
    "service_id": 1,
    "operator_code": "RB",
    "operator_name": "Robi",
    "short_name": null,
    "description": null,
    "logo": "robi.png",
    "is_active": true,
    "display_order": 0,
    "created_at": "2026-01-18T13:22:54.000000Z",
    "updated_at": "2026-01-18T13:22:54.000000Z"
  }
  // ... more operators
]

Normal Recharge

Submit a standard mobile recharge request with a specific amount.

POST /api/billing/service-requests/recharge/normal

Important: The reference field is required and must be unique. Duplicate references will be rejected.

Request Body:

Field Type Required Description
operator string Yes Operator code: gp, rb, at, bl, tt, sk
msisdn string Yes Mobile number (11 digits)
amount number Yes Recharge amount
service_type string No Service type: prepaid or postpaid
reference string Yes Unique reference ID (also accepts client_reference, clientReference)
webhook_url string No URL to receive transaction updates 
{
  "msisdn": "01712345678",
  "amount": 10,
  "operator": "gp",
  "service_type": "prepaid",
  "webhook_url": "https://your-domain.com/webhooks/recharge",
  "reference": "BILL-026401"
}
curl -X POST https://demo.irecharge.net/api/billing/service-requests/recharge/normal \
  -H "X-Open-Key: ok_test_YOUR_OPEN_KEY" \
  -H "X-Authorization: sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "01712345678",
    "amount": 10,
    "operator": "gp",
    "service_type": "prepaid",
    "webhook_url": "https://your-domain.com/webhooks/recharge",
    "reference": "BILL-026401"
  }'

Response (200 OK):

{
  "success": true,
  "message": "Recharge processed successfully",
  "billing": {
    "transactionId": 4,
    "reference": "BILL-026401",
    "status": "success",
    "rechargeRequestId": 5,
    "rechargeType": "normal",
    "operatorServiceId": 1,
    "amount": 10,
    "fee": 0.5,
    "commission": 1.5,
    "offerId": null
  }
}

Response Status Values: The status field can be success, processing, pending, failed, etc., depending on the transaction state.

Sandbox Mode: If using sandbox credentials (ok_test_*), transactions will be simulated with random success/failure responses for testing purposes.

Offer Recharge

Purchase special operator offers for mobile recharge.

Two-Step Process

  1. Get available offers for the mobile number
  2. Purchase the selected offer

Step 1: Get Available Offers

GET /api/billing/recharge/offers

Query Parameters:

Parameter Type Required Description
phone string Yes Mobile number
operator string Yes Operator code 
curl -X GET "https://demo.irecharge.net/api/billing/recharge/offers?phone=01937395849&operator=bl" \
  -H "X-Open-Key: ok_test_YOUR_OPEN_KEY" \
  -H "X-Authorization: sk_test_YOUR_SECRET_KEY"

Response (200 OK):

{
  "success": true,
  "message": "Offers fetched successfully.",
  "operator": "banglalink",
  "phone": "01937395849",
  "sessionContext": null,
  "purchase": {
    "method": "POST",
    "endpoint": "/api/billing/recharge/offers/purchase",
    "fallbackEndpoint": "/api/billing/service-requests/recharge/offer",
    "requiredFields": ["msisdn", "amount", "operator", "offer_id", "tran_id"],
    "optionalWebhookFields": ["webhook_url", "recharge_webhook_url"],
    "optionalReferenceFields": ["reference", "client_reference"]
  },
  "offers": [
    {
      "offerPrice": "219",
      "offerDescription": "25GB",
      "offerDescriptionBangla": "25GB",
      "offerValidityHours": "7 Days",
      "offerId": "OFF39814",
      "campaignId": null,
      "sessionContext": null,
      "optInKeyword": null,
      "ticketId": null,
      "tranId": "4576948674904374377",
      "totalCommission": "enc:...",
      "category": "INTERNET",
      "userCommission": 3.29,
      "commission": 3.29,
      "purchaseBody": {
        "msisdn": "01937395849",
        "amount": 219,
        "operator": "banglalink",
        "service_type": "prepaid",
        "recharge_type": "offer",
        "commission": 3.29,
        "offer_id": "OFF39814",
        "tran_id": "4576948674904374377"
      }
    }
    // ... more offers
  ]
}

Step 2: Purchase Offer

POST /api/billing/recharge/offers/purchase

Operator-Specific Fields:

  • GP: offer_id, campaign_id, session_context
  • Robi/Airtel: ticketId
  • Banglalink: offer_id, tran_id

Request Body (GP Example):

{
  "operator": "gp",
  "msisdn": "01712345678",
  "amount": 29,
  "recharge_type": "offer",
  "offer_id": "123456",
  "campaign_id": "cmp-123",
  "session_context": "ctx-xyz",
  "reference": "BILL-20260204-0002",
  "webhook_url": "https://example.com/webhooks/recharge"
}
curl -X POST https://demo.irecharge.net/api/billing/recharge/offers/purchase \
  -H "X-Open-Key: ok_test_YOUR_OPEN_KEY" \
  -H "X-Authorization: sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operator": "gp",
    "msisdn": "01712345678",
    "amount": 29,
    "recharge_type": "offer",
    "offer_id": "123456",
    "campaign_id": "cmp-123",
    "session_context": "ctx-xyz",
    "reference": "BILL-20260204-0002"
  }'

Response (200 OK):

{
  "success": true,
  "message": "Recharge processed successfully",
  "billing": {
    "transactionId": 5,
    "reference": "BILL-20260204-0002",
    "status": "success",
    "rechargeRequestId": 6,
    "rechargeType": "offer",
    "operatorServiceId": 1,
    "amount": 29,
    "fee": 0.5,
    "commission": 0.44,
    "offerId": "123456"
  }
}

Response Status Values: The status field can be success, processing, pending, failed, etc., depending on the transaction state.

Check Transaction Status

Check the status of a transaction by reference or transaction ID.

Flexible Lookup: You can check status using either your reference or the transaction_id returned during recharge.

Method 1: GET Request (by reference)

GET /api/billing/transactions/status/check 
curl --location 'https://demo.irecharge.net/api/billing/transactions/status/check?reference=BILL-20260204-0001' \
  --header 'X-Open-Key: ok_test_YOUR_OPEN_KEY' \
  --header 'X-Authorization: sk_test_YOUR_SECRET_KEY'

Method 2: GET Request with Body (by transaction_id)

GET /api/billing/transactions/status/check

Accepted lookup fields:

  • transaction_id or transactionId
  • reference, client_reference, or clientReference
curl --location --request GET 'https://demo.irecharge.net/api/billing/transactions/status/check' \
  --header 'X-Open-Key: ok_test_YOUR_OPEN_KEY' \
  --header 'X-Authorization: sk_test_YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 1
  }'

Response (200 OK):

{
  "success": true,
  "message": "Transaction status fetched successfully.",
  "data": {
    "transactionId": 1,
    "reference": "BILL-20260204-0001",
    "clientReference": "BILL-20260204-0001",
    "status": "success",
    "isFinal": true,
    "type": "service_purchase",
    "direction": "debit",
    "amount": 10,
    "fee": 0.5,
    "commission": 0,
    "gatewayReference": "DEMO_TRX_17703205542675",
    "serviceRequest": {
      "type": "recharge",
      "id": 1,
      "status": "success",
      "msisdn": "01712345678",
      "accountIdentifier": null,
      "offerId": null
    },
    "operator": {
      "id": 1,
      "code": "GP",
      "name": "Grameenphone"
    },
    "decision": {
      "mode": "auto",
      "reason": null
    },
    "createdAt": "2026-02-05T19:42:34.000000Z",
    "updatedAt": "2026-02-05T19:42:34.000000Z",
    "approvedAt": "2026-02-05T19:42:34.000000Z",
    "reversedAt": null
  }
}

Transaction Statuses:

pending

Awaiting processing

processing

Being processed

success

Completed successfully

failed

Transaction failed

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API credentials
402 Payment Required - Insufficient balance or no active API subscription
403 Forbidden - IP not whitelisted or account inactive
404 Not Found - Transaction not found
422 Validation Error - Missing/invalid parameters or duplicate reference
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format:

{
  "success": false,
  "message": "Insufficient balance",
  "error": "Your account balance is insufficient for this transaction",
  "code": "INSUFFICIENT_BALANCE"
}

Common Errors

HTTP Case Example Message
401 Missing/invalid API key headers Missing headers: X-Open-Key and X-Authorization are required.
422 Missing reference in billing recharge Billing recharge requires a unique reference in body (reference/client_reference).
422 Duplicate reference Reference already exists. Please send a unique reference.
404 Status check not found Transaction not found for provided identifier.
402 No active API subscription No active API subscription found.

IP Whitelist Restriction: If you receive a 403 error with message "Your IP address is not whitelisted", add your server IP to the whitelist in your Developer Dashboard.

Rate Limits

API rate limits vary by package:

Starter

60 requests/minute

Business

120 requests/minute

Enterprise

Custom limits

Rate limit headers are included in each response for monitoring.

Webhooks

Receive real-time notifications about transaction events. Set webhook URL in request body (webhook_url or recharge_webhook_url) or configure it in your API key settings.

Webhook Events

Event Description
billing.recharge.success Initial request accepted/processed response
billing.recharge.approved Transaction auto-approved or admin-approved
billing.recharge.rejected Transaction rejected or reversed
billing.banking.success Banking transaction created
billing.banking.approved Banking transaction approved
billing.banking.rejected Banking transaction rejected

Webhook Payload Example:

{
  "event": "billing.recharge.approved",
  "timestamp": "2026-02-04T20:10:12.000000Z",
  "api_key_id": 3,
  "user_id": 5,
  "transaction": {
    "id": 21,
    "reference": "BILL-20260204-0001",
    "status": "success"
  },
  "decision": {
    "action": "approved",
    "mode": "auto"
  }
}

Best Practice: Always verify webhook authenticity and respond with HTTP 200 to acknowledge receipt. Failed webhooks will be retried automatically.

Need Help?

Our support team is here to help you integrate our API successfully.

Email Support Call Us