Skip to Content
درگاه پرداخت و هسته مالیمعماری و فلوی پرداخت

معماری و فلوی پرداخت

این صفحه نشان می‌دهد یک تراکنش از کلیک کاربر تا فعال‌سازی اشتراک چه مسیری را طی می‌کند، و اصطلاحاتی را که در باقی مستند می‌بینید معرفی می‌کند.

اصطلاحات کلیدی

اصطلاحتوضیح
reference_idشناسه‌ای که شما تولید می‌کنید و در سیستم خود برای ردیابی تراکنش نگه می‌دارید. باید یکتا باشد.
hash_idشناسه‌ای که درگاه تولید می‌کند و در URL پرداخت و ادامه‌ی فلو از آن استفاده می‌شود.
pre-transactionدرخواست اولیه به درگاه برای دریافت hash_id و pay_url. مرحله‌ی اول هر پرداخت.
verifyتایید نهایی پرداخت. تا قبل از Verify، پول به حساب شما وارد نمی‌شود.
inquiryاستعلام وضعیت تراکنش، وقتی نمی‌دانید آیا پرداخت موفق بوده یا نه.
callback_urlآدرسی در سرور شما که درگاه بعد از پرداخت، کاربر را به آن برمی‌گرداند.
ref_idشماره مرجع تراکنش بانکی، که در رسید برای کاربر نمایش می‌دهید.
X-Gateway-Secretکلید امنیتی در همه‌ درخواست‌های API به درگاه.

فلوی کلی

┌──────────┐ ۱. انتخاب پلن ┌──────────────┐ │ کاربر │ ───────────────────▶ │ Frontend │ └──────────┘ └──────┬───────┘ ۲. POST /payment/initiate ┌──────────────┐ │ Backend │ └──────┬───────┘ ۳. ذخیره‌ی pending در DB │ ۴. POST /pay/pre-transactions ┌──────────────┐ │ درگاه باسلام │ └──────┬───────┘ ۵. بازگشت hash_id و pay_url ┌──────────────┐ │ Frontend │ ◀── ۶. Redirect به pay_url └──────┬───────┘ ۷. کاربر پرداخت می‌کند ┌──────────────┐ │ درگاه باسلام │ └──────┬───────┘ ۸. Redirect به callback_url ┌──────────────┐ │ Backend │ └──────┬───────┘ ۹. POST /pay/transactions/{hash_id}/verify ۱۰. بروزرسانی DB → status='verified' ۱۱. فعال‌سازی اشتراک کاربر ┌──────────────┐ │ صفحه‌ی موفقیت │ └──────────────┘

مراحل به زبان ساده

  1. Frontend: کاربر پلن یا کالا را انتخاب می‌کند و دکمه «پرداخت» را می‌زند.
  2. Backend (initiate): یک reference_id یکتا تولید می‌کنید، تراکنش را با status='pending' در دیتابیس خود ذخیره می‌کنید، سپس POST /pay/pre-transactions می‌زنید.
  3. درگاه: hash_id و pay_url برمی‌گرداند.
  4. Frontend: کاربر را به pay_url Redirect می‌کنید.
  5. پرداخت کاربر: در صفحه‌ی درگاه، کاربر کارت و رمز را وارد می‌کند.
  6. Callback: درگاه کاربر را به callback_url شما برمی‌گرداند با hash_id، reference_id، status و گاهی ref_id.
  7. Verify: اگر status === 'success' بود، POST /pay/transactions/{hash_id}/verify می‌زنید. تا اینجا پول هنوز در حساب شما تثبیت نشده است.
  8. به‌روزرسانی نهایی: تراکنش را verified می‌کنید، اشتراک کاربر را فعال می‌کنید، و کاربر را به صفحه‌ی موفقیت می‌برید.

اگر Verify را فراموش کنید، تراکنش در حالت معلق می‌ماند و درگاه پس از مدتی آن را Refund می‌کند. Verify نه اختیاری، بلکه گام نهایی الزامی است.

وضعیت‌های تراکنش

این وضعیت‌ها را در ستون status جدول payment_transactions نگه دارید:

وضعیتمعنی
pendingتراکنش ساخته شده، منتظر پرداخت کاربر است.
verifiedپرداخت موفق و در سیستم درگاه نهایی شده.
failedپرداخت ناموفق، لغوشده، یا Verify شکست خورده.
expired (اختیاری)کاربر در زمان مجاز پرداخت نکرده.
refunded (اختیاری)تراکنش به کاربر برگشت داده شده.

وضعیت‌های API درگاه

پاسخ verify و inquiry فیلد status.id دارد:

status.idمعنی
2در انتظار پرداخت
3پرداخت موفق
4پرداخت ناموفق
5پرداخت انجام شده ولی Verify نشده (unverified)

در کد خود همیشه status.id === 3 را چک کنید تا تراکنش را verified بدانید.

Last updated on