# POST /v2/invoice/payment/details

# Hub: Get Invoice Payment Details

این اندپوینت برای **استعلام وضعیت و دریافت جزئیات تراکنش** یک فاکتور خاص استفاده می‌شود.   
معمولاً پس از بازگشت کاربر از درگاه بانک، کلاینت با ارسال `slug` فاکتور به این اندپوینت، وضعیت نهایی پرداخت (موفق یا ناموفق)، شماره پیگیری، شماره کارت و علت خطا (در صورت شکست) را دریافت می‌کند.

<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/details`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** HubController@paymentSlugData</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) دارد.

</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>slug</td><td>string</td><td>**(الزامی)** شناسه منحصر به فرد (۸ کاراکتری) فاکتور که در مرحله ایجاد فاکتور تولید شده است.</td></tr></tbody></table>

</div>## Logic Details

فرآیند استعلام شامل مراحل دقیق زیر است:

<div class="api-docs" id="bkmrk-%D8%AC%D8%B3%D8%AA%D8%AC%D9%88%DB%8C-%D9%81%D8%A7%DA%A9%D8%AA%D9%88%D8%B1%3A-%D8%B3%DB%8C%D8%B3%D8%AA%D9%85">1. **جستجوی فاکتور:**
    - سیستم در جدول `airplus_invoices` به دنبال رکوردی با `slug` ارسال شده می‌گردد.
    - اگر رکوردی یافت نشود، پاسخ خطای `409` با پیام "سند ارسالی به بانک یافت نشد" بازگردانده می‌شود.
2. **پردازش داده‌های درگاه (Gateway Parsing):**
    - اگر فاکتور پیدا شد، ستون `result` (که حاوی پاسخ JSON از بانک است) پردازش می‌شود.
    - سیستم بر اساس نوع درگاه (`drive`)، اطلاعات **شماره پیگیری** و **شماره کارت** را استخراج می‌کند: 
        - **Behpardakht:** از فیلدهای `SaleReferenceId` و `CardHolderPan` استفاده می‌شود.
        - **Sep (Saman):** از فیلدهای `TraceNo` و `SecurePan` استفاده می‌شود.
    - همچنین رکورد قبض (Bill) مرتبط از جدول `airplus_bills` بازیابی می‌شود تا نوع سرویس (`object\_type`) مشخص گردد.
3. **بررسی وضعیت نهایی (Status Check):**
    - **حالت موفق (Status == 3):** اگر وضعیت فاکتور برابر با **3** باشد، پرداخت موفقیت‌آمیز بوده است. جزئیات کامل تراکنش با کد `200` ارسال می‌شود.
    - **حالت ناموفق (Status != 3):** اگر وضعیت هر چیزی غیر از 3 باشد: 
        1. پیام خطای دقیق از پاسخ بانک استخراج می‌شود (مثلاً `errorDesc` برای سامان یا پیام عمومی برای به‌پرداخت).
        2. پاسخ با کد وضعیت `409` ارسال می‌شود که حاوی جزئیات تراکنش + آبجکت `error` است.

</div>## Response Structure

### پاسخ موفق (پرداخت تایید شده)

<div class="api-docs" id="bkmrk-status-code%3A-200-ok">- **Status Code:** `200 OK`

</div>```json
{
    "payload": {
        "type": "hotel",
        "amount": 1500000,
        "tracking_code": "17459821",
        "drive": "sep",
        "datetime": "2024-05-18 14:30:00",
        "card": "610433******1234",
        "return_url": "https://client-app.com/callback"
    },
    "meta": {
        "timestamp": 1716025200
    }
}
```

### پاسخ ناموفق (خطای پرداخت یا یافت نشدن)

<div class="api-docs" id="bkmrk-status-code%3A-409-con">- **Status Code:** `409 Conflict`
- در این حالت، بادی پاسخ همچنان شامل اطلاعات تراکنش (در صورت وجود) است تا به کاربر نمایش داده شود، اما یک آبجکت خطا نیز دارد.

</div>```json
{
    "payload": {
        "type": "flight",
        "amount": 5000000,
        "tracking_code": null,
        "drive": "behpardakht",
        "datetime": "2024-05-18 14:35:00",
        "card": null,
        "return_url": null
    },
    "meta": {
        "timestamp": 1716025500
    },
    "error": {
        "code": 1000,
        "message": "خطای مربوط به پرداخت"
    }
}
```

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

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-find"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Find Invoice by `slug`</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Invoice Found?</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 409 (Not Found)</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Parse Gateway Data**  
Extract Tracking &amp; Card No based on driver (Sep/Behpardakht)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Status == 3 ?</div><div style="position: relative; padding-left: 50px; border-left: 2px dashed #ccc; margin-left: 50%; transform: translateX(-50%);"><div class="flow-arrow-label-left" style="top: -20px; left: -40px;">Yes</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 200 OK  
(Payment Details)</div><div class="flow-arrow-label-right" style="top: -45px; right: -30px;">No</div><div style="position: absolute; top: 40px; right: -80px; height: 50px; border-right: 2px dashed #ccc;">  
</div></div><div class="flow-arrow">↓ (No)</div><div class="flow-item-process" style="background-color: #ffebee;">**Extract Error Msg**  
Get specific error from gateway response</div><div class="flow-arrow">↓</div><div class="flow-item-error">Return 409 Conflict  
(Details + Error Obj)</div></div></div>