This API allows you to inquire the outstanding bill for an Iranian mobile number (postpaid). It uses Sepal Yar's mobile bill inquiry service and returns bill id, payment id, amount and operator. On successful calls, the service tariff is deducted from the caller's wallet.
/api/services/mobile-bill-inquiry/
The Mobile Bill Inquiry API lets you retrieve the outstanding bill for a postpaid Iranian mobile number using Sepal Yar's VAS services.
On each successful call, the service:
This API requires token-based authentication plus a unique code header.
Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODEIf authentication fails, a 401 Unauthorized response will be returned.
Send a POST request with application/json body.
Headers:
Authorization: Token YOUR_AUTH_TOKENX-Unique-Code: YOUR_UNIQUE_CODEContent-Type: application/jsonBody:
{
"mobile": "09131852730",
"midterm": true
}The midterm flag controls whether a midterm bill should be retrieved. If omitted, it defaults to true.
Successful responses include the following fields:
success: Boolean flag indicating successrequest_ref: Unique reference for the requestamount: Charged amount (in Rials)response_data: Bill information (bill_id, pay_id, amount, operator)response_time_ms: Upstream response timeerror_message: Null for successful callsOn failure, the response contains success: false and an error object with details.
The API uses standard HTTP status codes:
When Sepal Yar returns validation errors, the original payload (including errors array) is exposed under the error field.
bill_id and pay_id for payment flows.request_ref, ref_id and operation_time for auditing.| پارامتر | نوع | اجباری | توضیحات | مثال |
|---|---|---|---|---|
mobile
|
String | اجباری |
Postpaid mobile number in Iranian format (starting with 09) or international format (+98 or 0098). Spaces and dashes will be removed.
اعتبارسنجی: Must start with 09, +98 or 0098. Max length 20 characters. Only valid postpaid numbers are supported by upstream. |
09131852730
|
midterm
|
Boolean | اختیاری |
If true, inquires midterm bill (میاندوره). If false, may return final bill depending on operator rules. Default is true.
اعتبارسنجی: Boolean value; if omitted, defaults to true. |
True
|
Example using Python requests library.
import requests
url = "https://inquiry.sepal.ir/api/services/mobile-bill-inquiry/"
headers = {
"Authorization": "Token YOUR_AUTH_TOKEN",
"X-Unique-Code": "YOUR_UNIQUE_CODE",
"Content-Type": "application/json",
}
data = {
"mobile": "09131852730",
"midterm": true
}
response = requests.post(url, json=data, headers=headers)
print(response.json())Example using C# HttpClient.
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Token YOUR_AUTH_TOKEN");
client.DefaultRequestHeaders.Add("X-Unique-Code", "YOUR_UNIQUE_CODE");
var payload = new
{
mobile = "09131852730",
midterm = true
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://inquiry.sepal.ir/api/services/mobile-bill-inquiry/",
content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}Example using PHP cURL.
<?php
$url = "https://inquiry.sepal.ir/api/services/mobile-bill-inquiry/";
$data = [
"mobile" => "09131852730",
"midterm" => true
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Token YOUR_AUTH_TOKEN",
"X-Unique-Code: YOUR_UNIQUE_CODE",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>Command-line cURL example.
curl -X POST "https://inquiry.sepal.ir/api/services/mobile-bill-inquiry/" \
-H "Authorization: Token YOUR_AUTH_TOKEN" \
-H "X-Unique-Code: YOUR_UNIQUE_CODE" \
-H "Content-Type: application/json" \
-d '{
"mobile": "09131852730",
"midterm": true
}'Successful response with bill information.
{
"amount": "integer",
"success": "boolean",
"request_ref": "string",
"error_message": "null",
"response_data": {
"amount": "integer",
"pay_id": "string",
"ref_id": "string",
"bill_id": "string",
"operator": "string",
"operation_time": "integer"
},
"response_time_ms": "integer"
}{
"amount": 15000,
"success": true,
"request_ref": "XIHAUOLARKN7M0KLZKJTRNTNIPXUL7YZ",
"error_message": null,
"response_data": {
"amount": 242000,
"pay_id": "24246814",
"ref_id": "fa6da148-f0df-4be1-9808-cdf3c6e82ef9",
"bill_id": "7048364930150",
"operator": "MCI",
"operation_time": 1763304680412
},
"response_time_ms": 260
}Bad request - invalid parameters (e.g., malformed mobile).
{
"error": {
"code": "string",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}{
"error": {
"code": "INVALID_PARAMETERS",
"details": {
"mobile": [
"شماره موبایل باید با 09 شروع شود یا فرمت بینالمللی داشته باشد."
]
},
"message": "پارامترهای ورودی نامعتبر است."
},
"success": false
}Unauthorized - missing or invalid authentication headers.
{
"error": {
"code": "string",
"message": "string"
},
"success": "boolean"
}{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication credentials were not provided."
},
"success": false
}Payment Required - insufficient wallet balance.
{
"error": {
"code": "string",
"message": "string"
},
"success": "boolean"
}{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient wallet balance."
},
"success": false
}Unprocessable entity - Sepal Yar validation error (returned as-is).
{
"error": {
"errors": "list",
"ref_id": "string (optional)",
"operation_time": "integer (optional)"
},
"success": "boolean"
}{
"error": {
"errors": [
{
"code": "5001",
"message": "شماره موبایل نامعتبر است."
}
],
"ref_id": "fa6da148-f0df-4be1-9808-cdf3c6e82ef9",
"operation_time": 1763304680412
},
"success": false
}