You need to enable JavaScript to use this application.
POST استعلام

IBAN Validation API

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.

POST /api/services/iban-validation/
نیاز به احراز هویت Token 60 requests/minute

مستندات

Overview

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.

Authentication

Authentication

Requires both token and unique code headers.

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Requests without these headers return 401.

Request Format

Request Format

Send a POST request with JSON body:

{
  "iban": "IR110170000000219950976002"
}

IBAN must follow Iranian formatting (IR + 24 digits). Spaces are optional.

Response Format

Response Format

Successful responses include owner names, bank code/name, and deposit status. The wallet charge amount and request reference are also provided.

Error Handling

Error Handling

Common statuses: 400 (invalid IBAN), 401 (auth failure), 402 (insufficient balance), 422 (IBAN not found or upstream validation error), 502 (upstream outage).

Best Practices

Best Practices

  • Normalize IBAN by removing spaces before sending.
  • Store the returned request_ref for auditing.
  • Handle validation errors gracefully.
  • Monitor wallet balance to avoid 402 responses.
  • Use caching for repeated IBAN checks if business rules allow.

پارامترهای درخواست

پارامتر نوع اجباری توضیحات مثال
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

مثال‌های کد

Python Example

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())
C# Example

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);
    }
}
PHP Example

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;
?>
cURL Example

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"
  }'

فرمت پاسخ

200
پاسخ موفق

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
}
400
خطا

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
}
401
خطا

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
}
402
خطا

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
}
422
خطا

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
}
502
خطا

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
}