# POST /v2/invoice/payment/wallet

# Hub: Pay using Wallet

این اندپوینت یک فرآیند پرداخت ترکیبی را مدیریت می‌کند که به کاربر اجازه می‌دهد از **کیف پول داخلی شعبه** برای تسویه حساب استفاده کند.   
این مسیر دو سناریوی اصلی دارد:   
۱. **موجودی کافی:** مبلغ کامل از کیف پول کسر شده و تراکنش با موفقیت ثبت می‌شود.   
۲. **موجودی ناکافی:** موجودی کیف پول به طور کامل مصرف شده و برای باقیمانده مبلغ، یک لینک پرداخت آنلاین (از طریق اندپوینت `createInvoice`) ایجاد می‌شود.

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Finvoice%2Fpay"><div class="endpoint-info"><div>**URL:** `/v2/invoice/payment/wallet`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** HubController@payByWallet</div><div>**Middleware:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2-%D8%A8%D9%87-%D8%AA%D9%88%DA%A9%D9%86-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87">- نیاز به توکن احراز هویت (JWT) دارد.
- اطلاعات اپراتور و شعبه (`operator`, `branch`) توسط میدل‌ور به درخواست تزریق می‌شود.

</div>## Body Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>**(الزامی)** نوع موجودیتی که پرداخت برای آن انجام می‌شود. اگر مقدار آن `'bill'` باشد، مبلغ از روی رکورد قبض محاسبه می‌شود.</td></tr><tr><td>id</td><td>integer</td><td>**(الزامی)** شناسه موجودیت (مثلاً شناسه قبض یا سفارش).</td></tr><tr><td>amount</td><td>integer</td><td>**(شرطی)** مبلغ کل به ریال. ارسال این فیلد تنها زمانی الزامی است که `type` مقداری غیر از `'bill'` داشته باشد.</td></tr><tr><td>operator</td><td>object</td><td>**(تزریق سیستمی)** آبجکت اپراتور لاگین شده.</td></tr><tr><td>branch</td><td>integer</td><td>**(تزریق سیستمی)** شناسه شعبه‌ای که اپراتور به آن تعلق دارد.</td></tr></tbody></table>

</div>## Logic Details

این اندپوینت فرآیند پیچیده‌ای را دنبال می‌کند که به دو شاخه اصلی تقسیم می‌شود:

<div class="api-docs" id="bkmrk-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C-%D9%88-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8%D9%87-">1. **اعتبارسنجی و محاسبه مبلغ:**
    - بررسی می‌شود که فیلدهای `type` و `id` ارسال شده باشند.
    - **اگر `type` برابر با `'bill'` باشد:**
        - رکورد مربوطه از جدول `airplus_bills` با وضعیت `1` (فعال) جستجو می‌شود.
        - مبلغ نهایی از فرمول `($bill->amount + $bill->tax) - $bill->discount` محاسبه می‌شود.
        - اگر صورتحساب یافت نشود، خطای `422` بازگردانده می‌شود.
    - **در غیر این صورت:** مبلغ از فیلد `amount` در درخواست خوانده می‌شود.
    - مبلغ محاسبه شده باید حداقل **10,000 ریال** باشد.
2. **بررسی موجودی کیف پول:**
    - تابع `getBalanceWallet` فراخوانی شده تا موجودی فعلی کیف پول شعبه (`branch`) را دریافت کند.
    - شرایط بررسی می‌شود: اگر مبلغ مورد نیاز از موجودی کیف پول بیشتر باشد، به سناریوی "موجودی ناکافی" می‌رویم.
3. **سناریو ۱: موجودی ناکافی**
    - مبلغ باقیمانده (`$amount - $balance`) محاسبه می‌شود.
    - اگر مبلغ باقیمانده کمتر از 10,000 ریال باشد، برای ایجاد لینک پرداخت، حداقل مبلغ 10,000 ریال در نظر گرفته می‌شود.
    - یک درخواست جدید به صورت داخلی ساخته شده و به متد `createInvoice` **فوروارد می‌شود** تا برای مبلغ باقیمانده، یک لینک پرداخت آنلاین تولید کند.
    - خروجی این اندپوینت در این حالت، دقیقاً مشابه خروجی اندپوینت `createInvoice` خواهد بود (یک لینک پرداخت).
4. **سناریو ۲: موجودی کافی**
    - وضعیت صورتحساب (در جدول `airplus_bills`) به `5` (پرداخت شده از کیف پول) تغییر می‌کند.
    - یک رکورد **بدهی (Debit)** جدید در جدول `wallet` برای شعبه ثبت می‌شود. این رکورد شامل شناسه اپراتور، مبلغ کسر شده و توضیحات تراکنش است.
    - پاسخ موفقیت‌آمیز با کد `201` بازگردانده می‌شود که حاوی شناسه تراکنش کیف پول است.

</div>## Response Structure

### پاسخ موفق (پرداخت کامل از کیف پول)

<div class="api-docs" id="bkmrk-status-code%3A-201-cre">- **Status Code:** `201 Created`

</div>```json
{
    "payload": {
        "status": "succeed",
        "id": 542,
        "datetime": "2024-05-18 15:00:00"
    },
    "meta": {
        "timestamp": 1716027000
    }
}
```

### پاسخ موفق (پرداخت ترکیبی - موجودی ناکافی)

<div class="api-docs" id="bkmrk-status-code%3A-201-cre-1">- **Status Code:** `201 Created`
- در این حالت، پاسخ مشابه اندپوینت `createInvoice` است و شامل لینک پرداخت برای مبلغ باقیمانده می‌باشد.

</div>```json
{
    "payload": {
        "status": "payment_link",
        "amount": 450000,
        "url": "https://ipg.airplus.app/invoice/payment/kL9sW1aP"
    },
    "meta": {
        "timestamp": 1716027100
    }
}
```

### پاسخ‌های خطا

<div class="api-docs" id="bkmrk-status-code%3A-422-unp">- **Status Code:** `422 Unprocessable Entity`
- برای خطاهای اعتبارسنجی مانند عدم ارسال فیلد، یافت نشدن صورتحساب یا مبلغ کمتر از حد مجاز.

</div>```json
{
  "error": {
    "code": 1000,
    "message": "صورتحساب یافت نشد."
  },
  "meta": {
    "timestamp": 1716027200
  }
}
```

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

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-vali"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Validate Inputs &amp; Calculate Amount</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Inputs Valid &amp; Amount &gt;= 10k?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Return 422 (Validation Error)</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process" style="background-color: #e3f2fd;">Check Branch Wallet Balance</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Sufficient Balance?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: 0px; right: -30px;">No</div><div class="flow-arrow" style="float: right; margin-right: -100px;">↓</div><div class="flow-item-process" style="float: right; margin-right: -100px; background-color: #fff3e0;">Calculate Remainder</div><div class="flow-arrow" style="float: right; margin-right: -100px;">↓</div><div class="flow-item-process" style="float: right; margin-right: -100px; background-color: #fff3e0;">**Forward to `createInvoice`**</div><div class="flow-arrow" style="float: right; margin-right: -100px;">↓</div><div class="flow-item-success" style="float: right; margin-right: -100px;">Return 201 (Payment Link)</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process" style="background-color: #e8f5e9;">Update Bill Status to 5</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e8f5e9;">Create Debit Record in `wallet` table</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 201 (Succeed Status)</div></div></div>