Bill Query & Payment Confirmation API

Partially available

Endpoints for Education, ISP and Insurance bill query and payment confirmation — JSON over HTTPS.

Sandbox note: not testable in this sandbox

The Bill Query & Payment Confirmation API documented below (reproduced from the official SSLCOMMERZ developer documentation) is not implemented anywhere in this sandbox, so none of its four endpoints can be called here — it is reference material for merchants preparing a production integration for education/ISP/insurance bill collection. Confirm current availability and exact behavior with your SSLCOMMERZ contact before relying on it. What this sandbox can test is a different feature, the bill-query listener contract, documented at the end of this page under Sandbox Self-Test: Bill Query Listener Contract.

# Authentication

Headers required

Header Key	Value / Notes
API-KEY	Will be generated by the API provider and configured at SSLCOMMERZ end(required)
Authorization	Bearer <token> (optional if API-KEY used)
Content-Type	application/json

# 1. JWT Token Generation (Developer Login)

For obtaining access token using username & password

POST /api/v1/auth/token

Request Body

JWT Token Generation — request body
Parameter	Type	Required	Description
username	string	mandatory	Merchant API username.
password	string	mandatory	Password for the given username.

Sample Request — JWT Token

{
  "username": "merchant_api_username",
  "password": "merchant_api_password"
}

Sample Response — JWT Token

{
  "status": "success",
  "message": "Bill Found",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": "2025-12-31T23:59:59Z"
  }
}

# 2. Bill Query

POST /api/v1/bill/query

Request Body (common)

Bill Query — request body (common)
Parameter	Type	Required	Description
service_type	string	optional	One of `education`, `isp`, `insurance`
amount	number	optional	If known. Query allowed without it.
reference_id	string	mandatory	This information will be used to identify the payee and the outstanding bill on your end.
mobile_no	string	conditional	Required for education & isp — MSISDN (e.g. `01XXXXXXXXX`)
dob	string (YYYY-MM-DD)	optional	if applicable at your end
bill_month	string (YYYY-MM)	optional	Billing month if applicable.

Service-specific fields

Education : reference_id could be student_id (string)
ISP : reference_id could be the customer_no (string)
Insurance : reference_id could be the proposal_number (string)

Sample Request — Education

{
  "service_type": "education",
  "reference_id": "STU123456",
  "bill_month": "2025-09",
  "mobile_no": "01712345678",
  "dob": "2008-10-02"
}

Sample Response — Education

{
  "status": "success",
  "message": "Bill Found",
  "data": {
    "name": "Rahim Uddin",
    "reference_id": "STU123456",
    "bill_month": "2025-09",
    "amount_due": 5000,
    "due_date": "2025-10-15",
    "transaction_id": "TXN548257"
  }
}

Sample Request — ISP

{
  "service_type": "isp",
  "reference_id": "CUST89011",
  "mobile_no": "01898765432"
}

Sample Response — ISP

{
  "status": "success",
  "message": "Bill Found",
  "data": {
    "name": "XYZ Internet Client",
    "reference_id": "ISP123456",
    "package": "50 Mbps",
    "amount_due": 1500,
    "billing_cycle": "2025-10",
    "transaction_id": "TXN548257"
  }
}

Sample Request — Insurance

{
  "service_type": "insurance",
  "reference_id": "PROP112233",
  "amount": 7000
}

Sample Response — Insurance

{
  "status": "success",
  "message": "Premium Due",
  "data": {
    "name": "Abdul Karim",
    "reference_id": "INS123456",
    "amount_due": 7000,
    "due_date": "2025-11-30",
    "transaction_id": "TXN548257"
  }
}

Response Body (common)

Bill Query — response body (common)
Parameter	Type	Required	Description
name	string	optional	The customer name could be a student, an ISP user, or a policyholder based on your service.
amount_due	number	mandatory	The amount will be collected through the payment gateway.
reference_id	string	mandatory	This information will be used to identify the payee and the outstanding bill on your end. Your system must have the capability to process the due bill based on this parameter.
transaction_id	string	mandatory	It will be the unique ID that will be used by the payment gateway at the time of payment.

# 3. Payment Confirmation

POST /api/v1/bill/payment/confirm

Request Body

{
  "transaction_id": "TXN548257",
  "payment_approval_id": "APP548257",
  "reference_id": "STU123456",
  "amount": 5000
}

Sample Response — Confirm

{
  "status": "success",
  "message": "Payment Confirmed",
  "confirmation_id": "CONF987654321",
  "transaction_id": "TXN548257",
  "payment_approval_id": "APP548257",
  "data": {
    "service_type": "education",
    "amount": 5000
  }
}

# 4. Payment Confirmation Status

POST /api/v1/bill/payment/status

Request Body

{
  "transaction_id": "TXN548257",
  "reference_id": "STU123456"
}

Sample Response — Payment Confirmation Status

{
  "status": "success",
  "message": "Payment Success",
  "confirmation_id": "CONF987654321",
  "transaction_id": "TXN548257",
  "payment_approval_id": "APP548257",
  "details": {
    "service_type": "education",
    "amount": 5000
  }
}

# Error Responses & Status Codes

Error Response & Status Codes

{
  "status": "failed",
  "error_code": "BILL_NOT_FOUND",
  "message": "No bill available for provided information"
}

Status Codes:
200 - Success
400 - Invalid Request
404 - Bill Not Found
500 - Internal Server Error

# Notes & Recommendations

Validate phone numbers (E.164 recommended) and dates on client-side before calling API.
Send only fields required for the given service_type.
Use idempotency keys on payment confirmation requests if the same transaction might be submitted twice.
Log request/response pairs for troubleshooting (mask PII where necessary).

Generated API doc • JSON over HTTPS • © SSLCOMMERZ

# Test Payment Flow

Interactive tester available on the official developer site

The official SSLCOMMERZ page offers an interactive Test Payment Flow tool (opened from the “Test Payment Flow” button on developer.sslcommerz.com). That tool is not available in this sandbox; its flow is described below for reference only.

Sandbox Verification

Enter the characters from the image (not case sensitive) to use the sandbox test payment flow. (Captcha — Verify / Refresh)

The flow then runs in four steps:

Onboard
Bill Info
Bill Payment
Payment Status

Step 1: Onboard & Select Store

Onboarded Stores — Search and select a store to run the test payment flow (Search Store: search by Store ID or Utility Code; results are paged with Prev / Next).

Onboard New Merchant — provide:

Store ID (e.g., STORE001)
Base URL (e.g., https://merchant.com)
Token Endpoint (e.g., /login)
Bill Info Endpoint (e.g., /new-policy/bill-info)
Payment Endpoint (e.g., /new-policy/bill-pay)
Status Endpoint (e.g., /new-policy/bill-status)
Username
Password

Note: Stakeholder Code (SSLC) and Auth Key are hardcoded and will be used automatically for all API calls.

Then Onboard Merchant; the service list is fetched in the background (Fetch Service List).

Step 2: Bill Information

Fill in the bill information fields for the selected service and click Get Bill Info.

Step 3: Confirm Payment

Review the payment summary and click Process Payment.

Step 4: Payment Status

Click Check Status to query the payment status, or Start Again to restart the flow.

# Sandbox Self-Test: Bill Query Listener Contract

Sandbox-specific — not part of the official SSLCOMMERZ page

This section documents a different feature: the bill-query merchant-listener contract this sandbox actually implements and lets you test live via the Self-Test tool . It is unrelated to the four endpoints above.

When you run the Bill Query self-test, the sandbox looks up the subscription you specify, builds a signed JSON payload, and POSTs it to your bill_url — exactly like your production bill-query listener would receive.

Your endpoint receives

POST <your bill_url>

Bill query payload fields
Parameter	Type	Required	Description
total_amount	string	optional	The subscription's outstanding amount.
currency	string	optional	The subscription's currency.
tran_id	string	optional	A fresh transaction id generated for this query.
refer	string	optional	The reference value you supplied to the self-test form.
subscription_id	string	optional	The subscription id you supplied.
acct_no	string	optional	The subscription's account number.
store_id	string	optional	Your Store ID.
verify_key	string	optional	Comma-joined, alphabetically sorted list of the field names included in the signature (see below).
verify_sign_sha2	string	optional	SHA-256 signature over the sorted payload — see "Signature scheme" below.

Any additional fields stored against the subscription (fields_value) are merged into the payload as-is.

# Signature scheme

This signing scheme belongs to the sandbox self-test tool specifically and differs from production IPN signing (see the IPN Callbacks page). Do not assume the two are interchangeable.

The payload fields (plus a temporary store_passwd field set to sha256(your store password)) are sorted alphabetically by key. verify_key is the comma-joined list of those sorted field names. verify_sign_sha2 is sha256() of the sorted fields joined as key=value&key=value&.... The temporary store_passwd field is removed from the payload before it's sent — only verify_key and verify_sign_sha2 travel with the request.

# Response handling

Your endpoint should respond with your own bill-status JSON. Only the first 100 bytes of your response are captured and displayed back to you in the self-test results — this sandbox deliberately caps it (legacy's own version did not) since it's reflecting an arbitrary caller-chosen target's response back to them.