#P1513
POST /api/v2/gateway/details
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/gateway/details | V2CreditDebitController@paymentGatewayDetails | (none) | واکشی وضعیت و جزئیات فاکتور پرداخت از جدول payment_gateway بر اساس شناسه سریال پرداخت. |
منطق عملکرد تابع
تابع paymentGatewayDetails بر اساس مقدار serial_id که از سمت کلاینت ارسال میشود، رکورد متناظر در جدول payment_gateway را جستوجو میکند. در صورت پیدا شدن، نوع درگاه را مشخص کرده و بر اساس نوع درگاه (مانند behpardakht یا sep)، فیلدهای خروجی را از محتوای JSON ذخیرهشده در ستون result استخراج میکند.
برای درگاه behpardakht، پارامترهای CardHolderPan و SaleReferenceId استخراج میشود. اگر پاسخ شامل کد خطای ResCode=17 باشد، لینک retry ساخته میشود. برای درگاه sep نیز پارامترهای SecurePan و Rrn استفاده میگردد. درگاههای دیگر بدون پردازش JSON مستقیماً بازگردانده میشوند.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| serial_id | string | Body | بله | شناسه سریال فاکتور پرداخت، کلید اصلی جستوجو در جدول payment_gateway. |
خروجی (Response)
{
"payload": {
"drive": "sep",
"amount": 250000,
"card": "603799******1234",
"datetime": "1404-09-23 14:28",
"tracking_code": "123456789",
"try_link": false
},
"meta": {
"timestamp": 1732362504
}
}
در صورت خطا در فرایند پرداخت، ساختار پاسخ به صورت زیر است:
{
"error": {
"code": 1000,
"message": "در فرایند پرداخت مشکلی رخ داده است."
},
"payload": { ... },
"meta": { "timestamp": 1732362504 }
}
نکات امنیتی
- بهصورت پیشفرض فاقد middleware است، اما در حالت عملی باید
authWithJwtیا امضای دیجیتال اعمال شود. - شناسه
serial_idباید از منبع امن (callback تأییدشده) ارسال شود. - JSON ذخیرهشده در ستون
resultشامل دادههای حساس کارت است و نباید بدون masking به کاربر بازگردد.
نکات عملکردی
- جستوجو در جدول
payment_gatewayبر اساس ایندکس سریال انجام میگیرد (O(1)). - زمان پاسخ زیر ۵۰ ms است.
- هر دو جدول مرتبط
payment_gatewayوgatewaysفقط یکبار Query میشوند.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Http\Request;
- use Illuminate\Support\Facades\Response;
کدهای خطا
| کد | شرح خطا | منبع |
| 404 | رکورد سریال پرداخت یافت نشد. | DB::first() |
| 422 | پرداخت ناموفق یا ناتمام. | پردازش درگاه |
| 1000 | پیام پیشفرض خطای عمومی پرداخت در پاسخ JSON. | Exception Handler |
پیشنهادهای امنیتی
- اضافه کردن middleware تأیید سطح دسترسی یا امضای رمزنگاریشده در درخواستها.
- رمزگذاری جزئیات کارتها پیش از ذخیره در جدول.
- عدم ارسال پارامترهای خام
resultدر خروجی.
پیشنهادهای بهبود
- افزودن پشتیبانی از سایر درگاهها (مثلاً nextpay، idpay).
- افزودن وضعیت مجزا برای
timeoutوcanceled. - افزودن فیلد
verified_atدر خروجی برای همزمانسازی با جدول تراکنشها.
ممیزی و لاگها
- نوع لاگ:
GatewayDetails. - اقلام ممیزی: serial_id، آیپی درخواستدهنده، درگاه شناساییشده، نتیجه تراکنش.
- سطح حساسیت: Notice.
جمعبندی
تابع paymentGatewayDetails مسیر مرجع سیستم برای واکشی وضعیت نهایی پرداختها است. این endpoint خروجی استاندارد برای گزارش تراکنش ارائه میکند و بخشی از چرخهٔ پایش عملکرد درگاههای بانکی در زیرسیستم مالی محسوب میشود. اجرای امن و دقیق آن برای جلوگیری از مغایرت در دادههای بانکی ضروری است.