#P1809
POST /b2c/v1/wallet/credit
POST /b2c/v1/wallet/credit
این اندپوینت به کاربران B2C و همکاران (B2B/Colleague) اجازه میدهد تا از طریق درگاه پرداخت فعال دفتر خود، مبلغی را به کیفپولشان واریز کنند. نتیجه نهایی تولید لینک پرداخت منحصربهفرد با ساختار /p/{slug} است.
Endpoint Information
URL:
/b2c/v1/wallet/creditMethod: POST
Controller:
CreditDebitController@walletCreditMiddleware:
authWithJwtRelated Tables:
pays, payment_gateway, gateways, office_config, officesRequest Body Parameters
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| price | integer | ✅ | مبلغ واریز (حداقل 10000 ریال) |
| driver | string | ❌ | اختیاری؛ نوع درگاه بانکی (مثل sep یا behpardakht) |
| return_link | string (URL) | ❌ | آدرس بازگشت پس از پرداخت موفق |
| group | enum('b2c','colleague','b2b') | ✅ | گروه کاربر برای تنظیم نوع حساب مالی |
| branch | integer | ✅ | شناسه دفتر کاربر در سیستم |
| operator | object (JWT) | ✅ | شامل اطلاعات کاربر جاری (id, colleague_id, ...) |
Validation & Logic Flow
📥 ۱. دریافت پارامترها از بدنه درخواست
↓
بررسی فیلد price:
- ❌ در صورت خالی بودن → پاسخ با HTTP 422 و پیام «لطفا تمامی فیلدها را پر کنید»
- ❌ اگر مبلغ < 10000 → پاسخ با HTTP 422 و پیام «حداقل مبلغ قابل پرداخت 10000 ریال است»
- ✅ در غیر اینصورت → ادامه
↓
⚙️ ۲. فراخوانی
Functions::getGatewayConfig(branch, driver) برای یافتن درگاه فعال:
- اگر درگاه بهصورت مستقیم انتخاب شود (driver)، از جدول
gatewaysبررسی میگردد. - در غیر اینصورت مقدار پیشفرض از جدول
office_configبا کلیدDEFAULT_BANKING_GATEWAYاستخراج میشود. - ❌ در صورت نبودن درگاه فعال → پاسخ 400 با پیام «درگاه پرداخت فعال یافت نشد»
↓
تعیین نوع حساب بر اساس group:
- b2c → userType='b2c', objectType='customer', functorType='customer'
- colleague یا b2b → userType='b2b', objectType='colleague', functorType='colleague_user'
- ❌ سایر موارد → پاسخ 400 (پیام «گروه کاربری یافت نشد»)
↓
🧾 ۳. تولید رکورد جدید در جدول
pays با مشخصات:
- type='receive'
- moeen=14 (حساب معین برای شارژ کیف پول)
- type_pay='online'
- currency_amount = مبلغ درخواست شده
- status=1 (در انتظار پرداخت)
- year =
StaticController::getYearFinancial()
↓
💳 ۴. ایجاد رکورد در جدول
payment_gateway:
object_type='pay',object={id_pay}- مقدار
slugمنحصر به فرد باFunctions::generateSlugUnique(...) - تعیین لینک بازگشت (return_link) و شناسه درایو درگاه پرداخت
↓
✅ ۵. پاسخ موفق (HTTP 201): شامل اطلاعات پرداخت و لینک پرداخت آماده برای کاربر.
🎯 Response Samples
✅ موفق
{
"payload": {
"status": "payment_link",
"amount": 250000,
"url": "https://agency-domain.com/p/ABX21SD2",
"slug": "ABX21SD2",
"pay_id": 35876,
"gateway_id": 44
},
"meta": { "timestamp": 1733765953 }
}❌ فیلد ناقص
{
"error": {
"code": 1000,
"message": "لطفا تمامی فیلد ها را پر کنید."
},
"meta": { "timestamp": 1733765958 }
}❌ درگاه پیدا نشد
{
"error": {
"code": 1000,
"message": "درگاه پرداخت فعال یافت نشد"
}
}ساختار جدولهای مرتبط
| جدول | فیلدهای کلیدی | نقش |
|---|---|---|
pays |
type, serial, object_type, object, currency_amount, functor_type, functor_account, status | ثبت پرداخت در انتظار برای کیف پول |
payment_gateway |
slug, object_type, object, drive, amount, return | رهگیری پرداخت و ایجاد لینک پرداخت |
gateways |
id, bank, drive, branch, data(JSON) | مشخصات اتصال به درگاه بانکی |
office_config |
office, key='DEFAULT_BANKING_GATEWAY', value | تعیین درگاه پیشفرض شعبه |
توضیح توابع وابسته
- Functions::getGatewayConfig($branch, $drive): در صورتی که درگاه مشخص نشده باشد، مقدار پیشفرض (DEFAULT_BANKING_GATEWAY) را از پیکربندی دفتر میخواند.
- StaticController::getYearFinancial(): سال مالی را بر اساس تاریخ شمسی برمیگرداند (مثلاً 1404).
- Functions::generateSlugUnique('payment_gateway', 8): رشته یکتا برای URL پرداخت ایجاد میکند.
نکات فنی
- حداقل مبلغ مجاز پرداخت 10 000 ریال است.
- خطای عمومی برای group ناشناخته با پیام «گروه کاربری یافت نشد» بازگردانده میشود.
- status پرداخت در جدول
paysمقدار ۱ (در انتظار تأیید) دارد تا پس از بازگشت درگاه تغییر یابد. - لینک نهایی پرداخت از
offices.short_domainساخته میشود.