The IBAN & National Code Match API allows you to verify that an IBAN belongs to the owner of a specific national code. This is essential for KYC, AML, and payment compliance workflows.

When you call this API:

IBAN format is validated
National code format is validated
Sepal Yar verifies ownership
Wallet credits are deducted on success
A unique request reference is returned

Authentication

This API uses token-based authentication along with a unique code header.

Required Headers:

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Tokens can be obtained through the registration APIs. If authentication fails, a 401 error is returned.

Request Format

Requests must be sent as POST with JSON body.

Headers:

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE
Content-Type: application/json

Body:

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

Response Format

Success responses include:

success
request_ref
amount
response_data (operation_time, ref_id, iban_number, match)
response_time_ms

Errors include error.code, error.message, and optional details/errors.

Error Handling

Standard HTTP codes are used:

400 - Invalid parameters
401 - Authentication error
402 - Insufficient balance
404 - IBAN not found/invalid
500 - Internal error

Platform-specific errors (e.g., 1002) are returned under error.errors.

Use Cases

KYC and AML workflows
Payment gateway compliance
Account ownership verification
Preventing fraudulent withdrawals

Best Practices

Validate IBAN and national code format before calling API
Cache successful match results when possible
Store request_ref for future audits
Monitor wallet balance to avoid 402 errors
Retry transient 5xx errors with exponential backoff

Rate Limits

Default rate limit is 100 requests per minute per client. Exceeding the limit returns 429 Too Many Requests.

Pricing

Each successful request costs 10,000 Rials which is deducted from the wallet upon success.

Support

Provide the request_ref and ref_id when contacting support for faster resolution.

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

پارامتر	نوع	اجباری	توضیحات	مثال
`iban`	String	اجباری	شماره شبا (IBAN) که باید با IR شروع شود و دقیقاً 26 کاراکتر باشد. فقط اعداد پس از IR مجاز است. می‌توانید با یا بدون فاصله ارسال کنید. اعتبارسنجی: Must start with IR and be 26 characters. Only digits allowed after IR.	`IR110170000000219950976002`
`national_code`	String	اجباری	کد ملی صاحب حساب. باید فقط شامل اعداد باشد (10 تا 15 رقم). اعتبارسنجی: Must contain only digits. Length between 10 and 15 digits.	`4640229534`

مثال‌های کد

Python Example

Example using Python requests library

import requests
import json

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

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result.get("success"):
    print("Match result:", result["response_data"])
    print("Request ref:", result["request_ref"])
else:
    print("Error:", result.get("error"))

JavaScript Example

Example using fetch API

const url = "https://inquiry.sepal.ir/api/services/iban-national-code-match/";
const data = {
  iban: "IR110170000000219950976002",
  national_code: "4640229534"
};

fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "X-Unique-Code": "YOUR_UNIQUE_CODE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(result => {
    if (result.success) {
      console.log("Match result:", result.response_data);
    } else {
      console.error("Error:", result.error);
    }
  })
  .catch(error => console.error("Request failed:", error));

C# Example

Example using 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 data = new
        {
            iban = "IR110170000000219950976002",
            national_code = "4640229534"
        };

        var json = JsonSerializer.Serialize(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://inquiry.sepal.ir/api/services/iban-national-code-match/",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

PHP Example

Example using cURL in PHP

<?php

$url = "https://inquiry.sepal.ir/api/services/iban-national-code-match/";
$data = [
    "iban" => "IR110170000000219950976002",
    "national_code" => "4640229534"
];

$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;
?>

cURL Example

Command-line cURL example

curl --location 'https://inquiry.sepal.ir/api/services/iban-national-code-match/' \
  --header 'Authorization: Token YOUR_AUTH_TOKEN' \
  --header 'X-Unique-Code: YOUR_UNIQUE_CODE' \
  --header 'Content-Type: application/json' \
  --data '{
    "national_code": "4640229534",
    "iban": "IR110170000000219950976002"
  }'

فرمت پاسخ

200

پاسخ موفق

Successful response when IBAN matches the national code.

ساختار پاسخ:

{
  "amount": 10000,
  "success": true,
  "request_ref": "ABC123XYZ456DEF789",
  "error_message": null,
  "response_data": {
    "match": true,
    "ref_id": "936d16cb-9b23-47e4-8445-bf9ad3a1907c",
    "iban_number": "IR110170000000219950976002",
    "operation_time": 1763203972118
  },
  "response_time_ms": 1728
}

مثال پاسخ:

{
  "amount": 10000,
  "success": true,
  "request_ref": "ABC123XYZ456DEF789",
  "error_message": null,
  "response_data": {
    "match": true,
    "ref_id": "936d16cb-9b23-47e4-8445-bf9ad3a1907c",
    "iban_number": "IR110170000000219950976002",
    "operation_time": 1763203972118
  },
  "response_time_ms": 1728
}

401

خطا

Unauthorized - Authentication token missing or invalid.

ساختار پاسخ:

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication credentials were not provided."
  },
  "success": false
}

مثال پاسخ:

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication credentials were not provided."
  },
  "success": false
}

402

خطا

Payment required - Insufficient wallet balance.

ساختار پاسخ:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "موجودی کیف پول کافی نیست."
  },
  "success": false
}

مثال پاسخ:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "موجودی کیف پول کافی نیست."
  },
  "success": false
}

404

خطا

IBAN not found or not matched.

ساختار پاسخ:

{
  "error": {
    "code": "032",
    "errors": [
      {
        "code": "032",
        "message": "شماره شبا معتبر نمی باشد"
      }
    ],
    "message": "شماره شبا معتبر نمی باشد"
  },
  "success": false
}

مثال پاسخ:

{
  "error": {
    "code": "032",
    "errors": [
      {
        "code": "032",
        "message": "شماره شبا معتبر نمی باشد"
      }
    ],
    "message": "شماره شبا معتبر نمی باشد"
  },
  "success": false
}

400

خطا

Sepal Yar validation error (returned as-is).

ساختار پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "1002",
        "message": "ارسال شناسه بانک در header اجباری می باشد",
        "reference": "BANK-ID"
      }
    ],
    "ref_id": "74e0eafc-3d3f-4d0d-8af5-798cb2b50891",
    "operation_time": 1763203768922
  },
  "success": false
}

مثال پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "1002",
        "message": "ارسال شناسه بانک در header اجباری می باشد",
        "reference": "BANK-ID"
      }
    ],
    "ref_id": "74e0eafc-3d3f-4d0d-8af5-798cb2b50891",
    "operation_time": 1763203768922
  },
  "success": false
}