پرداخت قبوض خدماتی

مقدمه

امکان پرداخت قبوض آب، برق، گاز و... یکی از امکانات کلیدی مورد نیاز در اپلیکیشن‌های پرداخت و همچنین سامانه‌های مدیریت ساختمان است. به منظور پرداخت قبوض خدماتی، می‌توانید از این سرویس استفاده کنید. با ارائه شناسه قبض و شناسه پرداخت، می‌توانید انواع قبوض خدماتی را از طریق «سرزمین هوشمند پاد» پرداخت کنید. تمام قبوض خدماتی از جمله آب و فاضلاب، برق، گاز، تلفن ثابت و تلفن همراه (ایرانسل و رایتل) و خلافی خودرو با استفاده از این سرویس قابل پرداخت هستند.

پرداخت قبض (کیف پول)

جهت پرداخت قبوض خدماتی، لازم است شماره قبض و شناسه پرداخت را به سرویس زیر ارسال نمایید. در صورت موفقیت در پرداخت قبض، مبلغ در قالب یک فاکتور از حساب مربوط به دارنده‌ی توکن برداشته می شود و قبض پرداخت می‌گردد.

لازم به ذکر است، پرداخت قبوض تلفن همراه با این سرویس به صورت آنی است. همچنین امکان پرداخت قبض راهور ناجا از طریق این سرویس وجود ندارد. 

• شناسه سرویس: 27903493

پارامترهای ورودی:

• پارامتر های خروجی :

نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.

به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است.

• پارامتر های پاسخ سرویس در Result :

در صورتی که سرویس با موفقیت اجرا شده و پاسخ صحیح بازگرداند خروجی به صورت زیر است:

پاسخ برگشتی: json با ساختار و پارامترهای زیر

پرداخت قبض (درگاه)

 جهت پرداخت قبوض خدماتی به صورت دو مرحله‌ای، ابتدا فاکتور قبض توسط سرویس 27903191 صادر می‌گردد. در صورت صحت اطلاعات ارسالی، فاکتوری به مقدار مبلغ قبض مربوطه صادر شده و با هدایت کاربر به درگاه پرداخت، عملیات پرداخت قبض انجام می‌گردد.

توجه نمایید ارسال هر دو پارامتر billId و paymentId در سرویس زیر الزامی است. همچنین امکان پرداخت قبض راهور ناجا از طریق این سرویس وجود ندارد.

• شناسه سرویس: 27903191

نکته: با فراخوانی سرویس فوق، خروجی به شکل زیر دریافت می‌گردد. لازم به ذکر است، در صورت فراخوانی مجدد این سرویس، فاکتور جدید ایجاد نمی‌گردد و همان شناسه فاکتور ایجاد شده در خروجی نمایش داده خواهد شد.(در ا ینجا برخی قسمتهای خروجی حذف شده اند )

نکته: وضعیت قبوض صادر شده توسط سرویس فوق در لیست قبوض تا قبل از پرداخت، برابر با SERVICE_BILL_ISSUE_INVOICE است و پس از پرداخت قبض به SERVICE_BILL_ACCEPTED تغییر خواهد یافت.

• پارامتر های خروجی :

نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.

به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است.

• پارامتر های پاسخ سرویس در Result :

در صورتی که سرویس با موفقیت اجرا شده و پاسخ صحیح بازگرداند خروجی به صورت زیر است:

دریافت لینک پرداخت درگاه

کسب و کار میتواند برای تمام مشتریان خود، بدون نیاز به ورود به سامانه احراز هویت یکپارچه، امکان خرید را از طریق لینک زیر فراهم کند. برای این منظور لازم است کسب و کار از کد یکتا که برای فاکتور تولید می شود استفاده نماید.

مراحل انجام کار به ترتیب:

1. دریافت توکن جهت فراخوانی سرویس ها

2. ثبت فاکتور : دقت نمایید در صورت تمایل به نمایش شماره کارت های مربوط به مشتری، در صفحه درگاه ضروری است شناسه کاربر (userId) در فاکتور ثبت شود. این شناسه پس از ورود کاربر از طریق SSO بدست آمده یا می تواند شناسه ی کاربر آفلاین (غیر SSO) باشد. در صورتی که شماره موبایل مربوط به هیچکدام از این دودسته نیست، می توان با ثبت شماره موبایل (cellphoneNumber) در فاکتو، همین نتیجه را دریافت نمود.

3. هدایت کاربر به درگاه (توسط سرویس زیر)

4. استعلام فاکتور (اختیاری)

5. تایید پرداخت

6. بستن فاکتور (پس از اطمینان از تحویل محصول یا هرگونه شرط دلخواه کسب و کار به عنوان مجوز تسویه)

7. تسویه

سرویس اصلی: 46547342

سرویس سندباکس: 217462

پارامتر ورودی سرویس

پارامتر های خروجی :

نکته: پارامتر redirectUri  آدرسی است که پس از پرداخت، کاربر به آن هدایت می‌شود. پارامتر callUri  نیز می‌تواند آدرسی در سرور شما باشد که در صورت موفق بودن پرداخت، فراخوانی می‌گردد. پس از پرداخت، پارامترهای زیر به‌صورت GET  به آدرس redirectUri  ارسال می‌شوند.

توجه: در صورتی که پارامتر gateway  ارسال شود، کاربر مستقیماً به درگاه پرداخت بانک پاسارگاد منتقل می‌شود. در غیر این صورت، در صفحه‌ای که نمایش داده می‌شود، کاربر می‌تواند وارد SSO شود و از امکانات کیف پول خود نیز استفاده نماید.

اگر مقدارuniqueNumber  اشتباه ارسال شود، به صفحه‌ی "صفحه یافت نشد" هدایت خواهید شد

نمونه خروجی:

در صورت که پارامترها به درستی ارسال شده باشد نمونه زیر در خروجپ سرویس ایجاد خواهد شد که میتواند با فراخوانی آن در رابط کاربری مستقیم کاربر را به درگاه پرداخت هدایت نمود.

"در صورتی که پارامترها به درستی ارسال شده باشند، نمونه‌ی زیر در خروجی سرویس ایجاد خواهد شد که می‌تواند با فراخوانی آن در رابط کاربری مستقیم، کاربر را به

درگاه پرداخت هدایت کند."

کدهای خطای سرویس

پرداخت فاکتور صادر شده

مشتری جهت مشاهده فاکتور صادر شده و پرداخت آن از طریق درگاه، لازم است به آدرس زیر هدایت شده و با استفاده از پارامتر uniqueNumber قبض مربوطه را پرداخت نماید.

دقت نمایید که بجای مقدار private-call-address  مقادیر ادرس پرداخت درگاه به شکل زیر را قرار دهید.   

در محیط تست سندباکس =  https://sandbox.pod.ir:1033    

در محیط تولید و اصلی = https://pay.pod.ir

اگر مقدار uniqueNumber اشتباه ارسال شود، به صفحه "صفحه یافت نشد" هدایت می‌شوید.

 در صورتی که پارامتر PEP=gateway ارسال شود کاربر مستقیم به درگاه پرداخت بانک پاسارگاد متنقل می‌گردد، در غیر این صورت در صفحه‌ای که نمایش داده می‌شود کاربر می‌تواند وارد SSO شود و از امکانات کیف پول خود نیز استفاده نماید.

پارامتر redirectUri آدرسی است که بعد از پرداخت کاربر به آن هدایت می‌گردد، , و اطلاعات پرداخت به آن آدرس ارسال می شوند

پارامتر callUri نیز آدرسی در سرور شما می‌تواند باشد که در صورت موفق بودن پرداخت فراخوانی می‌گردد.و اطلاعات پرداخت به آن آدرس ارسال می شوند.

لازم به ذکر است، پس از پرداخت موفقیت‌آمیز قبوض، فاکتور به صورت اتوماتیک بسته خواهد شد و نیازی به بستن فاکتور نمی‌باشد.

GET [private-calls-address]/v1/pbc/payInvoiceByUniqueNumber/

? uniqueNumber= [the uniqueNumber in invoice] *

&redirectUri=[redirectURL]

&callUri= [The function that will be called at the end of payment]

gateway=PEP

اطلاعات پرداخت به صورت زیر به آدرسهای بازگشت کسب وکار، ارسال میشوند:

billNumber: شماره قبض که توسط خود کسب و کار در سرویس صدور فاکتور ارسال شده است.

  paymentBillNumber: شماره پرداخت

 invoiceId: شناسه فاکتور

 paid:  در صورتی که درصدور فاکتور پارامتر verificationNeeded مقدار true داشته باشد (پرداخت سه مرحله ای فعال شده است.) این مقدار false است . تا اینکه پرداخت توسط صادر کننده فاکتور( کسب وکار ) تایید شود. )، در غیر این صورت پس از یک ساعت، پول پرداخت شده به کیف پول کاربر برمی گردد.

terminalId: مقدار terminalId فقط در صورتی پر می شود که پارامتر wallet مقداری بجز PODLAND_WALLET داشته باشد.

maskedCardNumber: بخشی از شماره کارت پرداخت کننده

مقدار (rrn (reference number of shaprak transaction-شناسه انتقال وجه شاپرک، نیز به آدرس برگشت ارسال خواهد شد.

tref: مقدار tref شماره پیگیری تراکنش شاپرکی می باشد

وضعیت و لیست قبوض پرداختی

با این سرویس میتوان گزارش لیست قبوض پرداختی را دریافت کرد. برای دریافت وضعیت و لیست قبوض، فراخوانی این سرویس باید توسط توکن پرداخت کننده قبوض صورت بگیرد.

• شناسه سرویس: 3884760

پارامترهای ورودی:

پاسخ برگشتی:

آرایه‌ای با ساختار پاسخ سرویس "پرداخت قبض".

انواع قبض به صورت زیر است:

لغو قبض پرداختی

تا زمانی که وضعیت قبض SERVICE_BILL_ACCEPTED" است، برگشت تراکنش پرداخت قبض از طریق سرویس زیر امکان‌پذیر است. لازم به ذکر است، لغو قبوض همراه اول، امکان‌پذیر نمی‌باشد.

• شناسه سرویس: 3884767

پارامترهای ورودی:

پاسخ برگشتی:

در صورت لغو موفقیت­آمیز، پاسخی با ساختار سرویس قبلی دریافت می­شود که وضعیت قبض آن به SERVICE_BILL_CANCELED تغییر کرده است.

صحت سنجی شناسه قبض و شناسه پرداخت

شماره قبض حداقل 6 رقم می‌باشد:

شناسه پرداخت حداقل 6 رقم و حداکثر 13 رقم می‌باشد :

خطاهای رایج در سرویس صدور فاکتور پرداخت قبوض خدماتی