# POST /b2c/v1/wallet/credit

## POST /b2c/v1/wallet/credit

این اندپوینت به کاربران B2C و همکاران (B2B/Colleague) اجازه می‌دهد تا از طریق درگاه پرداخت فعال دفتر خود، مبلغی را به کیف‌پولشان واریز کنند. نتیجه نهایی تولید لینک پرداخت منحصر‌به‌فرد با ساختار `/p/{slug}` است.

<div class="api-docs" id="bkmrk-">---

</div>### Endpoint Information

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fwallet%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/wallet/credit`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** `CreditDebitController@walletCredit`</div><div>**Middleware:** `authWithJwt`</div><div>**Related Tables:** `pays`, `payment_gateway`, `gateways`, `office_config`, `offices`</div></div>---

</div>### Request Body Parameters

<div class="api-docs" id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA"><table class="schema-table" dir="rtl"><thead><tr><th>پارامتر</th><th>نوع</th><th>الزامی</th><th>توضیح</th></tr></thead><tbody><tr><td>price</td><td>integer</td><td>✅</td><td>مبلغ واریز (حداقل 10000 ریال)</td></tr><tr><td>driver</td><td>string</td><td>❌</td><td>اختیاری؛ نوع درگاه بانکی (مثل `sep` یا `behpardakht`)</td></tr><tr><td>return\_link</td><td>string (URL)</td><td>❌</td><td>آدرس بازگشت پس از پرداخت موفق</td></tr><tr><td>group</td><td>enum('b2c','colleague','b2b')</td><td>✅</td><td>گروه کاربر برای تنظیم نوع حساب مالی</td></tr><tr><td>branch</td><td>integer</td><td>✅</td><td>شناسه دفتر کاربر در سیستم</td></tr><tr><td>operator</td><td>object (JWT)</td><td>✅</td><td>شامل اطلاعات کاربر جاری (id, colleague\_id, ...)</td></tr></tbody></table>

---

</div>### Validation &amp; Logic Flow

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%DB%B1.-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87"><div class="flowchart" dir="rtl"><div class="flow-item">📥 ۱. دریافت پارامترها از بدنه درخواست</div><div class="flow-arrow">↓</div><div class="flow-item-decision">بررسی فیلد **price**: - ❌ در صورت خالی بودن → پاسخ با HTTP 422 و پیام «لطفا تمامی فیلدها را پر کنید»
- ❌ اگر مبلغ &lt; 10000 → پاسخ با HTTP 422 و پیام «حداقل مبلغ قابل پرداخت 10000 ریال است»
- ✅ در غیر این‌صورت → ادامه

</div><div class="flow-arrow">↓</div><div class="flow-item-process">⚙️ ۲. فراخوانی `Functions::getGatewayConfig(branch, driver)` برای یافتن درگاه فعال: - اگر درگاه به‌صورت مستقیم انتخاب شود (driver)، از جدول `gateways` بررسی می‌گردد.
- در غیر این‌صورت مقدار پیش‌فرض از جدول `office_config` با کلید `DEFAULT_BANKING_GATEWAY` استخراج می‌شود.
- ❌ در صورت نبودن درگاه فعال → پاسخ 400 با پیام «درگاه پرداخت فعال یافت نشد»

</div><div class="flow-arrow">↓</div><div class="flow-item-decision">تعیین نوع حساب بر اساس group: - **b2c** → userType='b2c', objectType='customer', functorType='customer'
- **colleague یا b2b** → userType='b2b', objectType='colleague', functorType='colleague\_user'
- ❌ سایر موارد → پاسخ 400 (پیام «گروه کاربری یافت نشد»)

</div><div class="flow-arrow">↓</div><div class="flow-item-process">🧾 ۳. تولید رکورد جدید در جدول `pays` با مشخصات: - type='receive'
- moeen=14 (حساب معین برای شارژ کیف پول)
- type\_pay='online'
- currency\_amount = مبلغ درخواست شده
- status=1 (در انتظار پرداخت)
- year = `StaticController::getYearFinancial()`

</div><div class="flow-arrow">↓</div><div class="flow-item-process">💳 ۴. ایجاد رکورد در جدول `payment_gateway`: - `object_type='pay'`, `object={id_pay}`
- مقدار `slug` منحصر به فرد با `Functions::generateSlugUnique(...)`
- تعیین لینک بازگشت (return\_link) و شناسه درایو درگاه پرداخت

</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ ۵. پاسخ موفق (HTTP 201): شامل اطلاعات پرداخت و لینک پرداخت آماده برای کاربر.</div></div>---

</div>### 🎯 Response Samples

#### ✅ موفق

```json
{
  "payload": {
    "status": "payment_link",
    "amount": 250000,
    "url": "https://agency-domain.com/p/ABX21SD2",
    "slug": "ABX21SD2",
    "pay_id": 35876,
    "gateway_id": 44
  },
  "meta": { "timestamp": 1733765953 }
}
```

#### ❌ فیلد ناقص

```json
{
  "error": {
    "code": 1000,
    "message": "لطفا تمامی فیلد ها را پر کنید."
  },
  "meta": { "timestamp": 1733765958 }
}
```

#### ❌ درگاه پیدا نشد

```json
{
  "error": {
    "code": 1000,
    "message": "درگاه پرداخت فعال یافت نشد"
  }
}
```

<div class="api-docs" id="bkmrk--1">---

</div>### ساختار جدول‌های مرتبط

<div class="api-docs" id="bkmrk-%D8%AC%D8%AF%D9%88%D9%84-%D9%81%DB%8C%D9%84%D8%AF%D9%87%D8%A7%DB%8C-%DA%A9%D9%84%DB%8C%D8%AF%DB%8C-%D9%86"><table class="schema-table" dir="rtl"><thead><tr><th>جدول</th><th>فیلدهای کلیدی</th><th>نقش</th></tr></thead><tbody><tr><td>`pays`</td><td>type, serial, object\_type, object, currency\_amount, functor\_type, functor\_account, status</td><td>ثبت پرداخت در انتظار برای کیف پول</td></tr><tr><td>`payment_gateway`</td><td>slug, object\_type, object, drive, amount, return</td><td>رهگیری پرداخت و ایجاد لینک پرداخت</td></tr><tr><td>`gateways`</td><td>id, bank, drive, branch, data(JSON)</td><td>مشخصات اتصال به درگاه بانکی</td></tr><tr><td>`office_config`</td><td>office, key='DEFAULT\_BANKING\_GATEWAY', value</td><td>تعیین درگاه پیش‌فرض شعبه</td></tr></tbody></table>

---

</div>### توضیح توابع وابسته

<div class="api-docs" id="bkmrk-functions%3A%3Agetgatewa">- **Functions::getGatewayConfig($branch, $drive)**: در صورتی که درگاه مشخص نشده باشد، مقدار پیش‌فرض (DEFAULT\_BANKING\_GATEWAY) را از پیکربندی دفتر می‌خواند.
- **StaticController::getYearFinancial()**: سال مالی را بر اساس تاریخ شمسی برمی‌گرداند (مثلاً 1404).
- **Functions::generateSlugUnique('payment\_gateway', 8)**: رشته یکتا برای URL پرداخت ایجاد می‌کند.

---

</div>### نکات فنی

<div class="api-docs" id="bkmrk-%D8%AD%D8%AF%D8%A7%D9%82%D9%84-%D9%85%D8%A8%D9%84%D8%BA-%D9%85%D8%AC%D8%A7%D8%B2-%D9%BE%D8%B1%D8%AF%D8%A7">- حداقل مبلغ مجاز پرداخت 10 000 ریال است.
- خطای عمومی برای group ناشناخته با پیام «گروه کاربری یافت نشد» بازگردانده می‌شود.
- **status** پرداخت در جدول `pays` مقدار ۱ (در انتظار تأیید) دارد تا پس از بازگشت درگاه تغییر یابد.
- لینک نهایی پرداخت از `offices.short_domain` ساخته می‌شود.

</div>