Skip to main content
#P1738

POST /v2/invoice/payment/wallet

Hub: Pay using Wallet

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

Request Overview

URL: /v2/invoice/payment/wallet
Method: POST
Controller: HubController@payByWallet
Middleware: authWithJwt

Access Control

  • نیاز به توکن احراز هویت (JWT) دارد.
  • اطلاعات اپراتور و شعبه (`operator`, `branch`) توسط میدل‌ور به درخواست تزریق می‌شود.

Body Parameters

Field Type Description
type string (الزامی) نوع موجودیتی که پرداخت برای آن انجام می‌شود. اگر مقدار آن 'bill' باشد، مبلغ از روی رکورد قبض محاسبه می‌شود.
id integer (الزامی) شناسه موجودیت (مثلاً شناسه قبض یا سفارش).
amount integer (شرطی) مبلغ کل به ریال. ارسال این فیلد تنها زمانی الزامی است که type مقداری غیر از 'bill' داشته باشد.
operator object (تزریق سیستمی) آبجکت اپراتور لاگین شده.
branch integer (تزریق سیستمی) شناسه شعبه‌ای که اپراتور به آن تعلق دارد.

Logic Details

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

  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 بازگردانده می‌شود که حاوی شناسه تراکنش کیف پول است.

Response Structure

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

  • Status Code: 201 Created
{
    "payload": {
        "status": "succeed",
        "id": 542,
        "datetime": "2024-05-18 15:00:00"
    },
    "meta": {
        "timestamp": 1716027000
    }
}

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

  • Status Code: 201 Created
  • در این حالت، پاسخ مشابه اندپوینت createInvoice است و شامل لینک پرداخت برای مبلغ باقیمانده می‌باشد.
{
    "payload": {
        "status": "payment_link",
        "amount": 450000,
        "url": "https://ipg.airplus.app/invoice/payment/kL9sW1aP"
    },
    "meta": {
        "timestamp": 1716027100
    }
}

پاسخ‌های خطا

  • Status Code: 422 Unprocessable Entity
  • برای خطاهای اعتبارسنجی مانند عدم ارسال فیلد، یافت نشدن صورتحساب یا مبلغ کمتر از حد مجاز.
{
  "error": {
    "code": 1000,
    "message": "صورتحساب یافت نشد."
  },
  "meta": {
    "timestamp": 1716027200
  }
}

Flowchart

Start Request
↓
Validate Inputs & Calculate Amount
↓
Inputs Valid & Amount >= 10k?
No
Return 422 (Validation Error)
↓ (Yes)
Check Branch Wallet Balance
↓
Sufficient Balance?
No
↓
Calculate Remainder
↓
Forward to `createInvoice`
↓
Return 201 (Payment Link)
↓ (Yes)
Update Bill Status to 5
↓
Create Debit Record in `wallet` table
↓
Return 201 (Succeed Status)
Back to top