#P1512
POST /gateway/invoice/{drive}/verify
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/gateway/invoice/{drive}/verify | V2CreditDebitController@gatewayInvoiceVerify | authWithJwt | بررسی وضعیت نهایی پرداخت (موفق، ناموفق یا در انتظار) و بهروزرسانی رکورد مربوطه در سیستم داخلی. |
منطق عملکرد تابع
تابع gatewayInvoiceVerify مرحلهٔ پایانی پرداخت الکترونیک است. این تابع پس از بازگشت کاربر از درگاه بانکی (با پارامترهای Authority، RefID یا معادل آنها) اجرا میشود.
سیستم اطلاعات پرداخت را از جدول payment_gateway بر اساس پارامتر {drive} واکشی کرده، شناسهٔ بانکی و مبلغ مورد انتظار را تطبیق میدهد. سپس از کنترلر درگاه (مثلاً ZarinpalController::verify()) برای استعلام نهایی وضعیت استفاده میکند.
در صورت موفقیت، رکورد پرداخت در جدول pays با وضعیت paid بهروزرسانی شده و تراکنش به عنوان سند مالی تأییدشده در دفتر ثبت میگردد.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| drive | integer | URL Param | بله | شناسه آیتم فاکتور آنلاین. |
| authority | string | Body / Callback | بله | شناسه تراکنش بازگشتی از درگاه (Authority یا Token). |
| status | string | Body / Callback | خیر | کد وضعیت برگشتی از درگاه (OK, NOK, ERROR). |
خروجی (Response)
{
"status": true,
"gateway": "zarinpal",
"invoice": {
"id": 114,
"reference": "A1Z4R36P",
"bank_ref": "000485298963",
"amount": 250000,
"state": "paid",
"verified_at": "1404-09-23 14:21"
},
"transaction": {
"accounting_record": 24039,
"updated_balance": 71250000
}
}
نکات امنیتی
- توکن JWT الزامی است، حتی در تماس callback.
- مقایسهٔ مبلغ پرداختشده با مبلغ ثبتشده پیش از تأیید ضروری است.
- تمام دادههای برگشتی از سمت درگاه (RefID, Status, CardPan و غیره) در جدول
gateway_logsنگهداری میشود.
نکات عملکردی
- میانگین زمان Verify برای Zarinpal حدود ۱۸۰–۲۵۰ میلیثانیه است.
- در صورت Timeout، سیستم تا سه بار verify مجدد با delay افزایشی انجام میدهد.
- پس از تأیید، کش Redis فاکتور در مدت ۶۰۰ ثانیه ابطال میشود.
وابستگیها
- use App\Http\Controllers\Gateways\ZarinpalController;
- use Illuminate\Support\Facades\DB;
- use App\Helpers\Functions;
- use Morilog\Jalali\Jalalian;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | پارامتر نامعتبر یا دادهٔ ناقص در Callback. | Validator |
| 403 | کاربر مجاز به تأیید این فاکتور نیست. | Auth Middleware |
| 404 | رکورد فاکتور یافت نشد. | Query |
| 409 | تأیید تکراری برای همان فاکتور انجام شد. | Duplicate Prevention |
| 500 | پاسخ نامعتبر از سرور درگاه. | Gateway Error |
پیشنهادهای امنیتی
- تمام Verifyها باید دارای signature hash اختصاصی باشند.
- در پاسخ درگاهها، مقادیر card_pan و card_hash نباید در لاگ سیستم اصلی نمایش داده شوند.
پیشنهادهای بهبود
- افزودن پشتیبانی از درگاههای چندارزی و پرداخت ارزی (EUR، AED، USD).
- افزودن هشدار بلادرنگ (WebSocket) در پنل مدیریتی در صورت پرداخت موفق.
- امکان trans-retry خودکار در صورت عدم اتصال لحظهای با بانک.
ممیزی و لاگها
- نوع لاگ:
GatewayVerify. - جزئیات: شناسه تراکنش، RefID، مبلغ پرداختشده، IP کاربر، زمان تأیید.
- سطح حساسیت: Critical Audit.
جمعبندی
تابع gatewayInvoiceVerify نقطهٔ نهایی فرایند پرداخت آنلاین است. این متد دادهٔ بازگشتی درگاه را با اطلاعات داخلی همگام کرده، وضعیت پرداخت را در پایگاه داده، کش و دفتر حسابداری ثبت میکند. اجرای صحیح آن برای جلوگیری از ثبت پرداختهای تکراری، حیاتی است و بخشی از چرخه اطمینان مالی (Financial Transaction Integrity Cycle) محسوب میشود.