استعلام تراکنش

آدرس سرویس: POST https:/carbon/v2.1/carbon_service/transaction_inquiry

---

شرح

این سرویس جهت استعلام تراکنش مورد استفاده قرار می گیرد.

---

نکات بسیار مهّم :

1) شرط موفق بودن تراکنش دریافت کد 0 در فیلد Status و موجود بودن مقدار عددی صحیح در فیلد tracking_number و خالی بودن فیلد errors می‌باشد.

2) در صورتی که کد پاسخ دریافت شده در فیلد Status غیر 0 باشد و فیلد error_code داخل شی errors عدم قطعیت در خصوص وضعیت تراکنش را اعلام کند لازم است با استفاده از سرویس‌های استعلام وضعیت درخواست مقدار صحیح تراکنش استعلام گردد. مانند کد خطای 5000 و 3000 و ... (کدهای خطایی که نیازمند استعلام وضعیت تراکنش می‌باشند در جدول شماره 2 مشخص شده‌اند. «ستون فراخوانی سرویس استعلام»)

3) باید توجه داشته باشیم که در صورت هر پاسخی غیر از 0 در فیلد Status حتماً فیلد errors و فیلد error_code داخل آن دارای مقدار صحیح خواهد بود.

نمونه مقدار فیلد errors به شکل ذیل است:

"errors": {
    "error_code": "8002",
    "error_description": "Transaction failed : Provider Error",
    "reference_name": "Mobile no is inactive or not registered.",
    "original_value": "charge error"
}

لذا در صورت دریافت هرگونه پاسخ غیر از 0 در فیلد Status که مقدار فیلد errors شامل مقدار نباشد و یا فیلد error_code داخل شی errors مقدار نداشته باشد باید به عنوان پاسخ غیر قطعی در نظر گرفته شود و برای مشخص شدن وضعیت صحیح تراکنش می‌بایست سرویس استعلام وضعیت تراکنش فراخوانی گردد.

Headers

مقادیر زیر باید در هدر قرار بگیرد

  Authorization : Bearer {Token}
  clientAddress : client IP
  

توجه : برای دریافت توکن مربوطه به بخش توکن مراجعه فرمایید

توضیحات

• Authorization: در این قسمت توکن دریافت شده از سرویس توکن را وارد نمایید

• clientAddress: آی پی مشتری نهایی که سرویس را دریافت کرده است .

Parameters

• request_number (نوع داده عددی) :(اجباری) این شناسه جهت پیگیری های بعدی مورد استفاده قرار می گیرد و پیشنهاد میگردد یه شناسه یکتا به ازای هر درخواست توسط سامانه مشتری تولید و به این سرویس ارسال گردد. سامانه ابری کربن هیچ کنترلی بر روی عدم تکراری بودن این مقدار انجام نمی دهد.

• tracking_number (نوع داده عددی) :(اجباری) کد رهگیری تراکنش.

• archive_search (نوع داده رشته) :(اجباری) جستجو در آرشیو .

• برای استعلام تراکنش یکی از پارامترهای tracking_number یا request_number ارسال گردد.

• در صورت ارسال هر دو پارامتر، پارامتر tracking_number لحاظ می‌گردد.

• پارامتر archive_search مقادیر true/false را می‌پذیرد و در صورتی که هیچ مقداری ارسال نگردد به صورت پیشفرض مقدار false را در نظر می‌گیرد.

• منظور از تراکنش‌های آرشیو شده، تراکنش‌های پیش از ساعت 00:00 دو روز پیش می‌باشد.

نمونه درخواست:

curl --location --request POST 'https:/carbon/v2.1/carbon_service/transaction_inquiry' \
--header 'Authorization: Bearer ....' \
--header 'Content-Type: application/json' \
--data-raw '{
    "request_number":"...."و
    "tracking_number":"...."و
    "archive_search":"...."
}

جواب موفق:

{
    "status": "0",
    "message": "تراکنش با موفقیت انجام شد",
    "timestamp": "....",
    "tracking_number": "....",
    ”request_number”: "....",
    "result": {
        "service_name": "topup_reserve",
        "request_body": {
            "mobile": "....",
            "merchant_name": "....",
            "card_number": "....",
            "channel_type": "....",
            "request_number": "....",
            "bank_id": "....",
            "national_code": "....",
            "product_id": "....",
            "amount": "...."
        },
        "response_body": {
            "status": "0",
            "message": "تراکنش با موفقیت انجام شد",
            "timestamp": "....",
            "tracking_number": "....",
            ”request_number”: "....",
            "result": {
                "reserve_number": "...."
            },
            "transaction_details": {
                "available_wallet_balance": "999641300",
                "provider_name": "....",
                "service_price": "0",
                "curency": "IRR",
                "remaining_number_of_calls": "9972",
                "remaining_number_of_calls_day": "9972"
            },
            "errors": {}
        }
    },
    "transaction_details": {
        "available_wallet_balance": "9000000",
        "provider_name": "....",
        "service_price": "0",
        "curency": "IRR",
        "remaining_number_of_calls": "9908",
        "remaining_number_of_calls_day": "9908"
    },
    "errors": {}
}

جواب ناموفق:

{
    "status": "1",
    "message": "تراکنش ناموفق",
    "timestamp": "....",
    "tracking_number": "....",
    ”request_number”: "....",
    "result": {},
    "transaction_details": {},
    "errors": {
        "error_code": "8029",
        "error_description": " Transaction failed : Provider  Error ",
        "reference_name": "reserve error.",
        "original_value": " خطا در ارائه سرویس دوباره سعی کنید "
    }
}

• status: عدد 0 به معنی موفق و عدد 1 به معنی ناموفق می باشد
• message: پاسخ از طرف سرویس سامانه ابری کربن
• timestamp: زمان و تاریخ درخواست
• request_number: شماره پیگیری ارسال شده در زمان فراخوانی
• tracking_number: شماره پیگیری ایجاد شده توسط سامانه ابری کربن جهت بررسی های بعدی
• result: آبجکتی از پاسخ سرویس شامل:
• request_body: نمونه درخواست ارسال شده
• reserve_number: شماره رزرو شده
• service_price: قیمت سرویس

در صورت بروز خطا در درخواست :

• errors: جزییات خطا
• error_code: کد مربوط به خطایی که پیش آمده است
• error_description: متن خطا
• reference_name: اطلاعات تکمیلی خطا
• original_value: اطلاعات تکمیلی خطا

---