Overview
The Card to IBAN API converts an Iranian debit card number into the corresponding IBAN using Sepal Yar. Use it to validate payout details before transferring funds.
POST
استعلام
Card to IBAN API
این API شماره کارت بانکی را دریافت کرده و شماره شبا متناظر را از سرویس سپال‌یار برمی‌گرداند. در صورت موفقیت هزینه سرویس از کیف‌پول کسر شده و درخواست در سیستم ثبت می‌شود.
POST
/api/services/card-to-iban/
نیاز به احراز هویت
Token
60 requests/minute
مستندات
Overview
Authentication
Authentication
Send both headers in every request:
Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODEMissing headers result in HTTP 401.
Request Format
Request Format
Send a POST request with JSON body:
{
"pan": "6037997139718010"
}The card number must be 16 digits and pass the Luhn algorithm.
Response Format
Response Format
Successful responses include the generated IBAN, bank metadata, and tracking references. Wallet deductions and request references are also included for auditing.
Error Handling
Error Handling
Common errors:
- 400: Invalid PAN provided.
- 401: Authentication headers missing or invalid.
- 402: Insufficient wallet balance.
- 422: The service rejected the card number.
- 500+: Unexpected upstream or internal errors.
Best Practices
Best Practices
- Validate the PAN on the client to avoid unnecessary calls.
- Cache IBAN results if the same card is queried frequently.
- Log the returned request_ref for troubleshooting.
- Handle validation errors gracefully and show localized messages.
پارامترهای درخواست
| پارامتر | نوع | اجباری | توضیحات | مثال |
|---|---|---|---|---|
pan
|
String | اجباری |
شماره کارت بانکی (PAN) با طول ۱۶ رقم. فقط اعداد مجاز است و از الگوریتم Luhn برای اعتبارسنجی استفاده می‌شود.
اعتبارسنجی: طول ۱۶ رقم، فقط اعداد، عبور از الگوریتم Luhn. |
6037997139718010
|
مثال‌های کد
Python Example
Example using Python requests library.
import requests
url = "https://inquiry.sepal.ir/api/services/card-to-iban/"
headers = {
"Authorization": "Token YOUR_AUTH_TOKEN",
"X-Unique-Code": "YOUR_UNIQUE_CODE",
"Content-Type": "application/json",
}
payload = {
"pan": "6037997139718010"
}
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
{
pan = "6037997139718010"
};
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/card-to-iban/",
content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}PHP Example
Example using PHP cURL.
<?php
$url = "https://inquiry.sepal.ir/api/services/card-to-iban/";
$payload = [
"pan" => "6037997139718010"
];
$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/card-to-iban/" \
-H "Authorization: Token YOUR_AUTH_TOKEN" \
-H "X-Unique-Code: YOUR_UNIQUE_CODE" \
-H "Content-Type: application/json" \
-d '{
"pan": "6037997139718010"
}'فرمت پاسخ
200
پاسخ موفق
پاسخ موفق شامل شماره شبا، اطلاعات بانک و مرجع پاسخ.
ساختار پاسخ:
{
"amount": "integer",
"success": "boolean",
"request_ref": "string",
"error_message": "null",
"response_data": {
"ref_id": "string",
"Bank-Id": "string",
"deposits": "string",
"last_name": "string",
"first_name": "string",
"iban_number": "string",
"operation_time": "integer (epoch milliseconds)"
},
"response_time_ms": "integer"
}مثال پاسخ:
{
"amount": 12000,
"success": true,
"request_ref": "4QL47QXABF07DHW7XHGBN3MNY6VY7NLC",
"error_message": null,
"response_data": {
"ref_id": "bae5ef76-ee7e-4aa0-b2ed-696f7d609714",
"Bank-Id": "MELIIR",
"deposits": "0219950976002",
"last_name": "علایی",
"first_name": "ر‌امین",
"iban_number": "IR110170000000219950976002",
"operation_time": 1762672009321
},
"response_time_ms": 210
}
400
خطا
پارامتر ورودی نامعتبر است (شماره کارت اشتباه).
ساختار پاسخ:
{
"error": {
"errors": "list",
"ref_id": "string",
"operation_time": "integer (epoch milliseconds)"
},
"success": "boolean"
}مثال پاسخ:
{
"error": {
"errors": [
{
"code": "1009",
"message": "برنامه به سرویس مورد نظر دسترسی نداشته و یا شما دسترسی آن را تایید ننموده اید"
}
],
"ref_id": "0cf63224-c849-4061-a018-47f7d1443243",
"operation_time": 1762669536847
},
"success": false
}
401
خطا
توکن یا کد یکتا ارسال نشده است.
ساختار پاسخ:
{
"error": {
"errors": "list",
"ref_id": "string",
"operation_time": "integer (epoch milliseconds)"
},
"success": "boolean"
}مثال پاسخ:
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication credentials were not provided."
},
"success": false
}
402
خطا
موجودی کیف‌پول کافی نیست.
ساختار پاسخ:
{
"error": {
"errors": "list",
"ref_id": "string",
"operation_time": "integer (epoch milliseconds)"
},
"success": "boolean"
}مثال پاسخ:
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient wallet balance."
},
"success": false
}
422
خطا
خطای اعتبارسنجی در سرویس سپال‌یار (شماره کارت ناشناخته).
ساختار پاسخ:
{
"error": {
"errors": "list",
"ref_id": "string",
"operation_time": "integer (epoch milliseconds)"
},
"success": "boolean"
}مثال پاسخ:
{
"error": {
"message": "SERVICE_FAILURE"
},
"success": false
}