راهنمای API پرداخت
اتصال اپلیکیشن یا وبسایت شما به درگاه پرداخت آیکلاسیک
Base URL: https://epay.iclassic.ir/ · Ver 5.0.1
۱. روند پرداخت
برای دریافت وجه از کاربر، سه مرحله اصلی دارید: ساخت تراکنش، هدایت مرورگر به درگاه، و تأیید نتیجه پس از بازگشت.
Merchant App ePay Bank
| | |
| 1. GET /pay/start | |
| id, price, site, callback | |
| ---------------------------->| insert (status=0) |
| <--- "{id}/{hash}" ----------| |
| | |
| 2. Redirect browser to | |
| /pay/go/{id}/{hash} | |
| ---------------------------->| bpPayRequest ------------->|
| | <-- RefId -----------------|
| | user pays on bank UI ----->|
| | <-- result POST -----------|
| | verify + settle |
| | status = 1 or 2 |
| 3. Redirect to callback | |
| <-- ...&status=ok|nok -------| |
| | |
| 4. GET /pay/check/{id}/{hash} (recommended) |
| ---------------------------->| JSON row |
۲. ایجاد تراکنش GET
/pay/start
یک رکورد پرداخت با وضعیت در انتظار میسازد و شناسهٔ امن برای ادامهٔ پرداخت برمیگرداند.
| پارامتر | الزامی | توضیح |
|---|---|---|
| id | بله | شناسه سفارش / مرجع شما در اپلیکیشن یا سایت |
| price | بله | مبلغ به ریال (مثلاً ۱۰۰۰۰۰ برای ۱۰٬۰۰۰ تومان) |
| site | توصیه میشود | برچسب اپ/سایت شما برای گزارشها (مثلاً my_shop) |
| callback | توصیه میشود | آدرس بازگشت کاربر، بهصورت هششده با الگوریتم url_hasher |
نمونه درخواست
https://epay.iclassic.ir/pay/start?id=34682&site=my_app&price=100000&callback=mysite.ir*pay*return_oid=34682
پاسخها (متن ساده، نه JSON)
| پاسخ | معنی |
|---|---|
| 5511/a1b2c3d4e5f6 | موفق — {id}/{hash} برای مرحله بعد |
| noidsent | پارامتر id ارسال نشده |
| nopricesent | پارامتر price ارسال نشده |
| 0 | ثبت تراکنش در دیتابیس ناموفق بود |
۳. هدایت کاربر به بانک GET
/pay/go/{id}/{hash}
پس از دریافت {id}/{hash} از مرحله قبل، مرورگر کاربر را به این آدرس بفرستید. صفحه بهصورت خودکار کاربر را به درگاه بانک ملت هدایت میکند.
https://epay.iclassic.ir/pay/go/5511/a1b2c3d4e5f6
- پارامتر اختیاری:
?ipg=mellat(پیشفرض) - اگر تراکنش قبلاً موفق باشد (
status=1)، پرداخت مجدد انجام نمیشود. - اگر قبلاً ناموفق باشد (
status=2)، امکان تلاش مجدد وجود دارد.
۴. بازگشت به سایت شما
پس از پرداخت (یا انصراف)، کاربر به آدرس کالبک شما هدایت میشود و پارامتر وضعیت به انتهای URL اضافه میگردد:
&status=ok— پرداخت تأیید و تسویه شد&status=nok— پرداخت ناموفق یا لغو شده
فقط به
status=ok در کالبک اعتماد نکنید. حتماً با /pay/check وضعیت را از سمت سرور تأیید کنید.
مثال آدرس نهایی بازگشت:
http://mysite.ir/pay/return?oid=34682&status=ok
۵. استعلام وضعیت GET
/pay/check/{id}/{hash}
وضعیت تراکنش را بهصورت JSON برمیگرداند. از همان {id}/{hash} دریافتی از /pay/start استفاده کنید.
https://epay.iclassic.ir/pay/check/5511/a1b2c3d4e5f6
نمونه پاسخ موفق
{
"id": "5511",
"site": "my_app",
"site_back": "mysite.ir*pay*return_oid=34682",
"pay_id": "34682",
"amount": "100000",
"data": "{... bank fields ...}",
"status": "1",
"date": "14050405",
"time": "193012"
}
خطاها
| پاسخ | معنی |
|---|---|
| {"ok":false,"error":"unauthorized"} | شناسه یا هش نامعتبر |
| false | تراکنش یافت نشد |
۶. هش کردن آدرس کالبک
قبل از ارسال پارامتر callback به /pay/start، URL بازگشت را با این الگوریتم ساده کد کنید:
// PHP
function url_hasher($url) {
$url = str_replace(['https://', 'http://'], '', $url);
$url = str_replace('/', '*', $url);
$url = str_replace(':', '#', $url);
$url = str_replace('?', '_', $url);
$url = str_replace('&', '-', $url);
return $url;
}
// ورودی: http://mysite.ir/pay/return?oid=34682
// خروجی: mysite.ir*pay*return_oid=34682
طول فیلد کالبک حداکثر حدود ۲۵۰ کاراکتر است. از آدرسهای کوتاه و پارامترهای ضروری استفاده کنید.
سیستم هنگام بازگشت، پروتکل را بهصورت
http:// بازسازی میکند؛ اگر سایت شما فقط HTTPS است، روی صفحهٔ بازگشت خودتان ریدایرکت امن انجام دهید یا از دامنهٔ HTTP سازگار استفاده کنید.
۷. نمونه کد PHP
function url_hasher($url) {
$url = str_replace(['https://', 'http://'], '', $url);
$url = str_replace(['/', ':', '?', '&'], ['*', '#', '_', '-'], $url);
return $url;
}
$orderId = 34682;
$amount = 100000; // Rials
$callback = url_hasher('http://mysite.ir/pay/return?oid=' . $orderId);
$base = 'https://epay.iclassic.ir';
$url = $base . '/pay/start?' . http_build_query([
'id' => $orderId,
'price' => $amount,
'site' => 'my_app',
'callback' => $callback,
]);
$res = @file_get_contents($url);
if ($res && $res !== '0' && strpos($res, '/') !== false) {
// Save $res (id/hash) in your DB for later /pay/check
header('Location: ' . $base . '/pay/go/' . $res);
exit;
}
die('Payment start failed: ' . $res);
صفحه بازگشت (تأیید)
// return.php — after redirect from ePay
$status = isset($_GET['status']) ? $_GET['status'] : '';
$oid = isset($_GET['oid']) ? $_GET['oid'] : '';
// Load saved epay id/hash for this order from YOUR database
$epayRef = '5511/a1b2c3d4e5f6'; // example
$check = @file_get_contents('https://epay.iclassic.ir/pay/check/' . $epayRef);
$row = json_decode($check, true);
if (is_array($row) && (string)$row['status'] === '1'
&& (string)$row['pay_id'] === (string)$oid) {
// Payment confirmed — fulfill the order
} else {
// Failed or pending
}
نمونه با cURL
curl -sG "https://epay.iclassic.ir/pay/start" \
--data-urlencode "id=34682" \
--data-urlencode "price=100000" \
--data-urlencode "site=my_app" \
--data-urlencode "callback=mysite.ir*pay*return_oid=34682"
۸. کدهای وضعیت تراکنش
| status | معنی |
|---|---|
| 0 | در انتظار پرداخت |
| 1 | موفق (تأیید و تسویه شده) |
| 2 | ناموفق / لغو شده |
۹. نکات مهم
- واحد مبلغ همیشه ریال است.
- CORS برای دامنهٔ API باز است (
Access-Control-Allow-Origin: *)؛ با این حال ساخت تراکنش را از سمت سرور انجام دهید، نه از مرورگر کاربر. {id}/{hash}برگشتی را در دیتابیس خود ذخیره کنید؛ برای استعلام و لینک درگاه لازم است.- فیلد
pay_idدر پاسخ check همانidارسالی شماست؛ فیلدidشناسه داخلی ePay است. - رسید انسانی:
https://epay.iclassic.ir/pay/receipt/{id}/{hash} - پرداخت دستی بدون API: https://epay.iclassic.ir/pay/manual
- کیت آماده «حمایت / خرید قهوه» برای کپی روی سایتهای دیگر: پوشه
donate/— فقطconfig.phpرا تنظیم کنید. نمایش نمونه
IClassic Payment API · Ver 5.0.1