مرکز راهنمایی توسعه دهندگان | درگاه پرداخت پارس پال

ارسال درخواست و دریافت لینک پرداخت

پس از آنکه در وب سایت پذیرنده تمامی مراحل انجام و سفارش مورد نیاز ثبت گردید و نیازمند ارسال کاربر جهت انجام پرداخت هستید می بایست با فراخوانی این تابع و ارسال اطلاعات مورد نیاز به پارس پال ، لینک مورد نیاز جهت هدایت کاربر به مراحل پرداخت را دریافت نمایید .

پارامتر های الزامی برای درخواست پرداخت amount و return_url هستند و با ارسال صحیح این دو پارامتر قادر به ارسال درخواست برای پرداخت هستید . توجه داشته باشید که تمام روال های داخلی پرداخت می بایست بر اساس نیاز شما طراحی و برنامه نویسی گردد و فرآیند های مورد نیاز ارتباطی به پارس پال نخواهد داشت .
به منظور شناسایی درخواست در هنگام بازگشت می توانید از پارامتر های reserve_id و یا order_id استفاده نمایید . هر مقداری که برای این دو فیلد ارسال گردد در پایان مراحل پرداخت ، مجدد به مسیر بازگشت POST خواهد شد ، این دو فیلد اختیاری می باشد و مقادیر آن اعتبار سنجی نخواهد شد و می تواند مقادیر عدد و رشته ای را در بر داشته باشد و یکتابودن آن نیز بررسی نمی گردد .

مشخصه payer نیز یک شئی از مشخصات پرداخت کننده می باشد که نام ، آدرس ایمیل و شماره موبایل را دریافت می نماید ، و ارسال آن اختیاری می باشد ، و در صورت ارسال ، این اطلاعات در پنل کاربری قابل مشاهده و گزارش گیری می باشد ، همچنین برروی اطلاعات ارسالی هیچ کنترل یا صحت سنجی انجام نمی گردد و مقدار موبایل تنها به صورت عددی قابل پذیرش می باشد . در صورتی که قصد یا امکان ارسال این اطلاعات را ندارید از ارسال اطلاعات ثابت برای همه درخواست ها خودداری نمایید و مقدار تهی یا نال ارسال نمایید .

پس از آماده سازی درخواست و ارسال آن نتیجه با فرمت درخواستی با پارامتر های مورد نیاز با وضعیت موفق یا خطا در فیلد status به شرح زیر بازگشت خواهد شد :

• ACCEPTED : پذیرش موفقیت آمیز درخواست

• FAILED : عدم پذیرش درخواست

پس از دریافت وضعیت ACCEPTED می بایست پرداخت کننده را برای شروع مراحل پرداخت به مسیر دریافتی در پارامتر link هدایت نمایید ، در صورتی که اطلاعات ارسالی نیز با مشکل مواجه باشد وضعیت FAILED خواهد شد ، همچنین در این حالت کد http پاسخ نیز 400 برگشت می گردد . در هنگام بروز مشکل در درخواست ، جزئیات خطا در فیلد error_type قابل دسترسی می باشد ، که شرح خطاهای معمول آن در زیر ذکر شده است ، همچنین به منظور سهولت در خطایابی در پارامتر message توضیحات و شرح خطا به صورت یک پیام فارسی اعلام می گردد :

• -2 UNAUTHORIZED : توکن شناسایی ApiKey ارسال نشده است

• -1 INVALID_APIKEY : توکن شناسایی ApiKey صحیح نمی باشد

• 1 INVALID_AMOUNT : مبلغ ارسالی صحیح نمی باشد

• 2 INVALID_RETURN_URL : مسیر بازگشت ارسالی صحیح نمی باشد

• 3 INVALID_CURRENCY : واحد پول ارسالی معتبر نمی باشد

• 4 INVALID_IP : آی پی ارسال کننده درخواست معتبر نمی باشد

• 10 INACTIVE_GATEWAY : درگاه/حساب غیر فعال است

• 11 BLOCKED_GATEWAY : درگاه/حساب مسدود شده است

• 12 NOTREADY_GATEWAY : درگاه راه اندازی نشده است

• 20 SERVICE_NOT_AVAILABLE : در حال حاضر سرویس در دسترس نمی باشد

• 30 BAD_REQUEST : محتوایی برای درخواست ارسال نشده است

• 99 UNKNOWN_ERROR : خطای تعریف نشده

مقادیر نوع خطا تماما با حروف بزرگ هستند ، همچنین error_code نیز شناسه عددی هر خطا را بازگشت می دهد

توجه فرمایید که روال های داخلی وب سایت شما می بایست توسط برنامه نویس پیاده سازی و یا توسط افزونه یا سیستم مدیریت محتوای خاص انجام گردد ، برای مثال اگر نیاز دارید کاربر با انتخاب محصول و ثبت سفارش نسبت به پرداخت اقدام نماید می بایست این مراحل برروی وب سایت شما پیاده سازی و اطلاعات مورد نظر از قبیل نوع محصول ، مبلغ ، کاربر و ... ذخیره و در هنگام نیاز به پرداخت با اتصال به API پارس پال مسیر مورد نیاز جهت انجام فرآیند پرداخت توسط کاربر را دریافت نمایید .

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

در پاسخ درخواست پرداخت payment_id یک شناسه یکتا به منظور شناسایی و استعلام پرداخت می باشد که بر اساس نیاز در پروژه ها یا اپلیکیشن ها می توانید با استفاده از آن به صورت لحظه ای از وضعیت و جریان پرداخت مطلع شوید ، جهت دریافت اطلاعات می بایست این شناسه را به تابع inquiry ارسال نمایید .

پارامتر default_psp یک فیلد اختیاری است که می توانید با ارسال کد شرکت پرداخت ، درخواست هدایت مستقیم کاربر را به صفحه پرداخت شاپرک اعلام نمایید ، این پارامتر در جزئیات ترمینال درگاه در پنل کاربری قابل مشاهده است ، همچنین در صورتی که شرکت پرداخت یا ترمینال قادر به پاسخگویی نباشد به صورت خودکار ترمینال شرکت پرداخت دیگری جایگزین خواهد شد .

پارامتر currency یک فیلد اختیاری است که در صورت عدم ارسال آن ، مبلغ ارسال شده در درخواست پرداخت بر اساس تنظیمات درگاه شناسایی خواهد شد ، در صورتی که مقدار این فیلد در هنگام ارسال درخواست تعیین گردد ملاک اصلی برای محاسبه مبلغ می باشد و به صورت خودکار تبدیل واحد پردازش خواهد شد ، مقادیر زیر برای واحد پول قابل ارسال می باشند .

• IRR : واحد پول ریال

• IRT : واحد پول تومان

تایید و اعتبار سنجی صحت عملیات پرداخت

پس از انجام یا انصراف از پرداخت ، کاربر به مسیر بازگشتی اعلامی توسط شما هدایت خواهد شد ، پیش از هر چیز به این نکته توجه داشته باشید که تحویل محصول و یا ثبت سفارش در وب سایت شما تنها منوط به ارسال شماره رسید پرداخت به این تابع و دریافت تاییدیه آن می باشد و وضعیت status تنها به منظور اطلاع رسانی از وضعیت تراکنش به صورت POST ارسال می گردد و به هیچ وجه قابل استناد برای تکمیل فرآیند خرید نخواهد بود !

، در هنگام ارسال کاربر اطلاعات مورد نیاز برای اعتبار سنجی پرداخت از طریق متد POST به وب سایت شما ارسال خواهد شد که توضیحات این پارامتر ها در زیر ذکر شده است :

• status : وضعیت انجام فرآیند توسط کاربر

• receipt_number : شماره رسید پرداخت

• payment_id : شناسه درخواست پرداخت

• reserve_id : شناسه رزرو - این مقدار هنگام درخواست پرداخت اعلام شده است

• order_id : شناسه سفارش - این مقدار هنگام درخواست پرداخت اعلام شده است

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

• 100 : کاربر عملیات پرداخت را انجام داده است

• 99 : انصراف کاربر از پرداخت

• 88 : پرداخت ناموفق

• 77 : لغو پرداخت توسط کاربر

در صورتی که وضعیت برابر با 100 دریافت گردد شما می بایست عملیات اعتبار سنجی و تایید پرداخت را از طریق API انجام دهید ، در این حالت پارامتر receipt_number در بردارنده شماره رسید پرداخت کاربر می باشد که با ارسال آن به تابع verify می بایست از صحت انجام تراکنش مطمئن شوید ، توجه فرمایید که وضعیت status با مقدار 100 نشان دهنده پرداخت موفق نمی باشد و تکمیل خرید برای تحویل سفارش به کاربر فقط می بایست با دریافت تاییدیه از طریق API صورت پذیرد .

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

• SUCCESSFUL : تایید شماره رسید پرداخت

• VERIFIED : شماره رسید قبلا تایید گردیده است

• AMOUNT_NOT_MATCH : مبلغ اعلامی جهت تایید پرداخت با مبلغ پرداخت شده همخوانی ندارد

• INVALID_RECEIPT_NUMBER : شماره رسید پرداخت معتبر نمی باشد

توجه فرمایید در صورتی که پارامتر واحد پول در هنگام درخواست پرداخت توسط شما اعلام گردد ، در هنگام تایید نیز می بایست واحد پول به شکل صحیح ارسال گردد همچنین در صورت وجود خطا در درخواست verify خطا های آن با درخواست پرداخت مشترک بوده و از طریق پاسخ خطای 400 و پارامتر error_type بازگشت داده خواهد شد .