معماری و فلوی پرداخت
این صفحه نشان میدهد یک تراکنش از کلیک کاربر تا فعالسازی اشتراک چه مسیری را طی میکند، و اصطلاحاتی را که در باقی مستند میبینید معرفی میکند.
اصطلاحات کلیدی
| اصطلاح | توضیح |
|---|---|
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'
۱۱. فعالسازی اشتراک کاربر
│
▼
┌──────────────┐
│ صفحهی موفقیت │
└──────────────┘مراحل به زبان ساده
- Frontend: کاربر پلن یا کالا را انتخاب میکند و دکمه «پرداخت» را میزند.
- Backend (initiate): یک
reference_idیکتا تولید میکنید، تراکنش را باstatus='pending'در دیتابیس خود ذخیره میکنید، سپسPOST /pay/pre-transactionsمیزنید. - درگاه:
hash_idوpay_urlبرمیگرداند. - Frontend: کاربر را به
pay_urlRedirect میکنید. - پرداخت کاربر: در صفحهی درگاه، کاربر کارت و رمز را وارد میکند.
- Callback: درگاه کاربر را به
callback_urlشما برمیگرداند باhash_id،reference_id،statusو گاهیref_id. - Verify: اگر
status === 'success'بود،POST /pay/transactions/{hash_id}/verifyمیزنید. تا اینجا پول هنوز در حساب شما تثبیت نشده است. - بهروزرسانی نهایی: تراکنش را
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