Overview
The IBAN Validation API retrieves information about an Iranian IBAN through Sepal Yar. Use it to confirm account ownership, bank, and status before proceeding with payouts or settlements.
This API validates an Iranian IBAN and returns metadata such as bank name, owner information, deposit number, and status. A successful call charges the wallet and stores the response for auditing.
/api/services/iban-validation/
The IBAN Validation API retrieves information about an Iranian IBAN through Sepal Yar. Use it to confirm account ownership, bank, and status before proceeding with payouts or settlements.
Requires both token and unique code headers.
Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODERequests without these headers return 401.
Send a POST request with JSON body:
{
"iban": "IR110170000000219950976002"
}IBAN must follow Iranian formatting (IR + 24 digits). Spaces are optional.
Successful responses include owner names, bank code/name, and deposit status. The wallet charge amount and request reference are also provided.
Common statuses: 400 (invalid IBAN), 401 (auth failure), 402 (insufficient balance), 422 (IBAN not found or upstream validation error), 502 (upstream outage).
| پارامتر | نوع | اجباری | توضیحات | مثال |
|---|---|---|---|---|
iban
|
String | اجباری |
Iranian iban (Sheba) number. Must start with IR and contain 26 characters when spaces are removed.
اعتبارسنجی: Must start with IR, numeric afterwards, total length 26 characters. |
IR110170000000219950976002
|
Example using Python requests library.
import requests
url = "https://inquiry.sepal.ir/api/services/iban-validation/"
headers = {
"Authorization": "Token YOUR_AUTH_TOKEN",
"X-Unique-Code": "YOUR_UNIQUE_CODE",
"Content-Type": "application/json",
}
payload = {
"iban": "IR110170000000219950976002"
}
response = requests.post(url, json=payload, 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
{
iban = "IR110170000000219950976002"
};
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/iban-validation/",
content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
Example using PHP cURL.
<?php
$url = "https://inquiry.sepal.ir/api/services/iban-validation/";
$payload = [
"iban" => "IR110170000000219950976002"
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
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/iban-validation/" \
-H "Authorization: Token YOUR_AUTH_TOKEN" \
-H "X-Unique-Code: YOUR_UNIQUE_CODE" \
-H "Content-Type: application/json" \
-d '{
"iban": "IR110170000000219950976002"
}'
Successful response containing IBAN details and owner info.
{
"amount": "integer",
"success": "boolean",
"request_ref": "string",
"error_message": "null",
"response_data": {
"ref_id": "string",
"bank_code": "string",
"bank_name": "string",
"owners_info": "list",
"deposit_number": "string",
"operation_time": "integer (epoch milliseconds)",
"deposit_iban_status": "string",
"deposit_iban_status_code": "string"
},
"response_time_ms": "integer"
}
{
"amount": 15000,
"success": true,
"request_ref": "X8BNORCZYSYBVIPLOMIXJBPDPQK6AYMM",
"error_message": null,
"response_data": {
"ref_id": "ffced284-263b-4751-91a9-621f967bf635",
"bank_code": "017",
"bank_name": "ملی",
"owners_info": [
{
"last_name": "علایی",
"first_name": "رامین"
}
],
"deposit_number": "0219950976002",
"operation_time": 1762629953669,
"deposit_iban_status": "ACTIVE",
"deposit_iban_status_code": "02"
},
"response_time_ms": 3258
}
Bad request due to invalid IBAN format.
{
"error": {
"code": "string (optional)",
"errors": "list (optional)",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}
{
"error": {
"code": "INVALID_PARAMETERS",
"details": {
"iban": [
"شماره شبا باید ۲۶ کاراکتر (IR + 24 رقم) باشد."
]
},
"message": "پارامترهای ورودی نامعتبر است."
},
"success": false
}
Unauthorized when auth headers are missing.
{
"error": {
"code": "string (optional)",
"errors": "list (optional)",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication credentials were not provided."
},
"success": false
}
Payment required because of insufficient wallet funds.
{
"error": {
"code": "string (optional)",
"errors": "list (optional)",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient wallet balance."
},
"success": false
}
Sepal Yar validation error or IBAN not found.
{
"error": {
"code": "string (optional)",
"errors": "list (optional)",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}
{
"error": {
"message": "SERVICE_FAILURE"
},
"success": false
}
Bad gateway when Sepal Yar returns unexpected errors.
{
"error": {
"code": "string (optional)",
"errors": "list (optional)",
"details": "object (optional)",
"message": "string"
},
"success": "boolean"
}
{
"error": {
"code": "SERVICE_ERROR",
"message": "خطا در فراخوانی سرویس: Upstream timeout."
},
"success": false
}