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

IBAN National Code Birthday Validation API

This API verifies whether an IBAN belongs to a person who has the provided national code and Jalali birth date. On success the wallet tariff is deducted and a match flag is returned from Sepal Yar.

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

مستندات

Overview

Overview

The IBAN National Code Birthday Validation API checks whether a given IBAN belongs to a user identified by a national code and Jalali birth date. It is useful for preventing fraud, validating bank payouts, and enforcing KYC regulations.

On successful calls the wallet is charged, the Sepal Yar match flag is returned, and the request is logged with a unique reference.

Authentication

Authentication

This endpoint requires both the API token and the user's unique code.

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Requests missing these headers will fail with 401 Unauthorized.

Request Format

Request Format

Send a POST request with JSON body:

{
  "iban": "IR110170000000219950976002",
  "national_code": "4640229534",
  "birth_date": "13790514"
}

The birth date must be Jalali (yyyyMMdd). Convert from Gregorian before calling the API.

Response Format

Response Format

Successful responses include a match flag plus Sepal Yar metadata:

  • request_ref: Unique request identifier
  • amount: Charged tariff (rial)
  • response_data.match: True when IBAN ownership is confirmed
  • response_time_ms: Upstream latency

Failures contain success: false and detailed error information.

Error Handling

Error Handling

Typical HTTP status codes:

  • 400 Bad Request: Invalid payload (e.g. wrong Jalali format)
  • 401 Unauthorized: Missing authentication headers
  • 402 Payment Required: Insufficient wallet balance
  • 422 Unprocessable Entity: The service rejected the parameters
  • 502 Bad Gateway: Sepal Yar service outage or timeout

Best Practices

Best Practices

  • Validate national code and convert birth dates to Jalali yyyyMMdd on the client.
  • Cache successful matches when business rules allow to reduce repeated lookups.
  • Log the returned request_ref for auditing and dispute resolution.
  • Monitor wallet balance to prevent 402 responses.
  • Implement retry logic with exponential backoff for transient 5xx errors.

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

پارامتر نوع اجباری توضیحات مثال
iban String اجباری Iranian IBAN (Sheba) number. Must begin with IR and contain 26 characters when spaces are removed.
اعتبارسنجی: Must start with IR and contain 24 numeric characters afterwards.
IR110170000000219950976002
national_code String اجباری National code / legal entity code / foreigner ID. Personal codes are 10 digits, legal entities 11 digits, and foreign IDs 12-15 digits.
اعتبارسنجی: Numeric only. Length 10, 11 or 12-15 digits depending on person type.
4640229534
birth_date String اجباری Jalali birth date in yyyyMMdd format (for example 13790514). Client must convert from Gregorian if needed.
اعتبارسنجی: Numeric only. 8 digits. Valid Jalali month/day range.
13790514

مثال‌های کد

Python Example

Example using Python requests library.

import requests

url = "https://inquiry.sepal.ir/api/services/iban-national-code-birthday-validation/"
headers = {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "X-Unique-Code": "YOUR_UNIQUE_CODE",
    "Content-Type": "application/json",
}
payload = {
    "iban": "IR110170000000219950976002",
    "national_code": "4640229534",
    "birth_date": "13790514"
}

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",
            national_code = "4640229534",
            birth_date = "13790514"
        };

        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-national-code-birthday-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-national-code-birthday-validation/";
$payload = [
    "iban" => "IR110170000000219950976002",
    "national_code" => "4640229534",
    "birth_date" => "13790514"
];

$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-national-code-birthday-validation/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "IR110170000000219950976002",
    "national_code": "4640229534",
    "birth_date": "13790514"
  }'

فرمت پاسخ

200
پاسخ موفق

Successful match when IBAN owner information matches the provided national code and birth date.

ساختار پاسخ:
{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": {
    "match": "boolean",
    "ref_id": "string",
    "operation_time": "integer (epoch milliseconds)"
  },
  "response_time_ms": "integer"
}
مثال پاسخ:
{
  "amount": 25000,
  "success": true,
  "request_ref": "FOIL3MGGTHTWIBUDMQWX9XL1VDMJ7IDI",
  "error_message": null,
  "response_data": {
    "match": true,
    "ref_id": "b37fcbed-de58-478d-a8f4-45b7890d41ad",
    "operation_time": 1762629133140
  },
  "response_time_ms": 4182
}
400
خطا

Validation error from our API (e.g. malformed birth date).

ساختار پاسخ:
{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "details": {
      "birth_date": [
        "طول تاریخ تولد باید ۸ رقم باشد (yyyyMMdd)."
      ]
    },
    "message": "پارامترهای ورودی نامعتبر است."
  },
  "success": false
}
401
خطا

Authentication error when token or unique code is 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 when wallet balance is insufficient.

ساختار پاسخ:
{
  "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 (for example invalid jalali date or national code).

ساختار پاسخ:
{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "errors": [
      {
        "code": "071",
        "value": "2000-08-04",
        "message": "پارامتر یا پارامترهای ورودی به درستی وارد نشده است",
        "reference": "birth_date"
      }
    ],
    "ref_id": "3ef074ef-e87d-439d-b762-757918b8dcca",
    "operation_time": 1762628903624
  },
  "success": false
}
502
خطا

Bad gateway when Sepal Yar is unreachable or returns an unexpected error.

ساختار پاسخ:
{
  "error": {
    "code": "string (optional)",
    "errors": "list (optional)",
    "details": "object (optional)",
    "message": "string"
  },
  "success": "boolean"
}
مثال پاسخ:
{
  "error": {
    "code": "SERVICE_ERROR",
    "message": "خطا در فراخوانی سرویس: Upstream timeout."
  },
  "success": false
}