Skip to main content
#P1737

POST /v2/invoice/payment/details

Hub: Get Invoice Payment Details

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

Request Overview

URL: /v2/invoice/payment/details
Method: POST
Controller: HubController@paymentSlugData
Middleware: authWithJwt

Access Control

  • نیاز به توکن احراز هویت (JWT) دارد.

Body Parameters

Field Type Description
slug string (الزامی) شناسه منحصر به فرد (۸ کاراکتری) فاکتور که در مرحله ایجاد فاکتور تولید شده است.

Logic Details

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

  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 است.

Response Structure

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

  • Status Code: 200 OK
{
    "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
    }
}

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

  • Status Code: 409 Conflict
  • در این حالت، بادی پاسخ همچنان شامل اطلاعات تراکنش (در صورت وجود) است تا به کاربر نمایش داده شود، اما یک آبجکت خطا نیز دارد.
{
    "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": "خطای مربوط به پرداخت"
    }
}

Flowchart

Start Request
↓
Find Invoice by `slug`
↓
Invoice Found?
No
Return 409 (Not Found)
↓ (Yes)
Parse Gateway Data
Extract Tracking & Card No based on driver (Sep/Behpardakht)
↓
Status == 3 ?
Yes
↓
Return 200 OK
(Payment Details)
No

↓ (No)
Extract Error Msg
Get specific error from gateway response
↓
Return 409 Conflict
(Details + Error Obj)
Back to top