درگاه پرداخت نکست پی

مستندات اتصال به وب سرویس

مقدمه

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

مراحل ایجاد یک تراکنش

هر تراکنش شامل 5 مرحله اصلی است :

1- ایجاد توکن
2- هدایت کاربر به صفحه بانک
3- انجام پرداخت توسط کاربر
4- بازگشت به سایت یا اپلیکیشن پذیرنده
5- استعلام صحت تراکنش و تایید آن

همچنین برای تراکنش های موفق ، در صورت نیاز به کنسل کردن یا عودت تراکنش میتوان مرحله ششم را اجرا کرد
6- عودت و لغو تراکنش موفق

برای دسترسی به لیست کد های وضعیت :
پیوست 1 - لیست کد های وضعیت

راهنمای وب سرویس تسویه حساب ( تسهیم / برداشت وجه ) :
CheckOut WebServices

راهنمای وب سرویس های استعلامی :
Inquiry WebServices

برای دسترسی به Sample Code های زبان های مختلف :
نمونه کد : PHP
نمونه کد : NodeJs
نمونه کد : Python
نمونه کد : Java
نمونه کد : cURL
نمونه کد : #C
نمونه کد : C
نمونه کد : Go
نمونه کد : Dart

1- ایجاد توکن

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

اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/token

پارامتر	عنوان	نوع	ضرورت	مثال
`api_key`	کلید مجوز دهی	uuid	اجباری	`b11ee9c3-d23d-414e-8b6e-f2370baac97b`
`order_id`	شماره سفارش	string	اجباری	`85NX85s427`
`amount`	مبلغ (پیش فرض تومان)	integer	اجباری	`74250`
`callback_uri`	آدرس بازگشت	URL	اجباری	`https://yourWebsite.com/callback`
`currency`	واحد پولی	string	اختیاری	`IRT` یا `IRR`
`customer_phone`	موبایل پرداخت کننده	numeric	اختیاری	`09121234567`
`custom_json_fields`	اطلاعات دلخواه	json	اختیاری	`{ "productName":"Shoes752" , "id":52 }`
`payer_name`	نام پرداخت کننده	string	اختیاری	`احمد احمدی`
`payer_desc`	توضیحات دلخواه	string	اختیاری	`متن توضیحات دلخواه`
`auto_verify`	تایید خودکار بدون نیاز به فراخوانی وریفای	string	اختیاری	`yes`
`allowed_card`	شماره کارت مجاز	string	اختیاری	`6104331111117890`

* نکته : با ارسال (( شماره موبایل پرداخت کننده )) ، اگر شخص پرداخت کننده قبلا در درگاه بانک اطلاعات کارت خود را ذخیره کرده باشد ، دیگر نیازی به ورود شماره 16 رقمی کارت و تاریخ انقضا نخواهد داشت
* اگر پارامتر auto_verify با مقدار yes ارسال شود ، تراکنش بدون تایید از طرف شما ، به طور خودکار تایید میشود . دقت فرمایید که درصورت استفاده از این پارامتر اگر ارتباط شما در هنگام کالبک با نکست پی برقرار نشود ، تراکنش به طور خودکار تایید میشود و ممکن است شما از نتیجه ی آن آگاه نشوید بنابراین این پارامتر را فقط در صورتی استفاده کنید که به هر ترتیب ( حتی در صورت قطعی سرور شما ) میخواهید تراکنش تایید شود.
* اگر پارامتر allowed_card با مقدار 16 رقمی کارت خاصی مقدار دهی شود ، اگر تراکنش با شماره کارتی غیر از شماره کارتی که شما اعلام میکنید انجام شود ، برگشت میخورد . بنابراین اگر میخواهید تراکنش با هر شماره کارتی پذیرفته شود ، این پارامتر را خالی بگذارید یا مقدار دهی نکنید .

پاسخ

پاسخ در قالب json شامل موارد زیر خواهد بود

پارامتر	عنوان	نوع	ضرورت	مثال
`code`	کد پاسخ	integer	اجباری	`-1`
`trans_id`	توکن تراکنش	uuid	اجباری	`f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1`

* نکته : اگر پارامتر code در پاسخ دارای مقدار 1- باشد، یعنی توکن با موفقیت صادر شده است و trans_id همان توکن مورد نیاز برای مراحل بعدی است.
* نکته : جهت پیگیری تراکنش در مراحل بعدی و جلوگیری از برخی خطرات مانند دابل اسپندینگ ، لازم است در دیتابیس خود ، trans_id مذکور را به همراه مبلغ و شماره سفارش ، ذخیره کنید.

2- هدایت کاربر به صفحه بانک

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

اند پوینت : https://nextpay.org/nx/gateway/payment/["trans_id"]
مثال : https://nextpay.org/nx/gateway/payment/f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1

بنابراین در این مرحله فقط کافیست کاربر را به آدرس مذکور در بالا ریدایرکت و هدایت کنیم .

3- انجام پرداخت توسط کاربر

در این مرحله کاربر وارد صفحه بانک تحت آدرس shaparak.ir شده است و میبایست اطلاعات کارت بانکی عضو شتاب خود، شامل شماره 16 رقمی ، CVV2 ، تاریخ انقضا و رمز دوم یا رمز دوم پویای خود را وارد کند و پرداخت را تکمیل کند.

4- بازگشت به سایت یا اپلیکیشن پذیرنده

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

پارامتر	عنوان	نوع	مثال
`trans_id`	توکن تراکنش	uuid	`f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1`
`order_id`	شماره سفارش	string	`85NX85s427`
`amount`	مبلغ (تومان)	integer	`74250`

5- استعلام و تایید تراکنش

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

اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/verify

پارامتر	عنوان	نوع	ضرورت	مثال
`api_key`	کلید مجوز دهی	uuid	اجباری	`b11ee9c3-d23d-414e-8b6e-f2370baac97b`
`trans_id`	توکن تراکنش	uuid	اجباری	`f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1`
`amount`	مبلغ (تومان)	integer	اجباری	`74250`
`currency`	واحد پولی	string	اختیاری	`IRT` یا `IRR`

پاسخ

پاسخ در قالب json شامل موارد زیر خواهد بود

پارامتر	عنوان	نوع	مثال
`code`	کد وضعیت تراکنش	integer	`0`
`amount`	مبلغ (تومان)	integer	`74250`
`order_id`	شماره سفارش	string	`85NX85s427`
`card_holder`	کارت پرداخت کننده	string	`5022-29-**-5020`
`customer_phone`	موبایل پرداخت کننده	numeric	`09121234567`
`Shaparak_Ref_Id`	کد پیگیری شاپرک	string	`141196584609`
`custom`	اطلاعات دلخواه	json	`{ "productName":"Shoes752" , "id":52 }`
`created_at`	تاریخ شمسی و زمان تراکنش	yyyy-mm-dd hh:mm:ss	`1397-01-01 14:16:17`

* نکته : اگر پارامتر code در پاسخ دارای مقدار 0 باشد، یعنی تراکنش (( موفق )) بوده است . هر مقداری غیر از صفر به معنی ناموفق بودن تراکنش است.

6- عودت و لغو یک تراکنش موفق

ممکن است به هر دلیلی شما بخواهید یک تراکنش موفق را (( عودت )) دهید و آنرا لغو کنید تا به حساب پرداخت کننده برگردد . دقت فرمایید که برای عودت یک تراکنش موفق حداکثر 20 دقیقه پس از تایید تراکنش، فرصت دارید پارامتر های زیر را از طریق متد POST به اندپوینت زیر ارسال کنید.

اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/verify

پارامتر	عنوان	نوع	ضرورت	مثال
`api_key`	کلید مجوز دهی	uuid	اجباری	`b11ee9c3-d23d-414e-8b6e-f2370baac97b`
`trans_id`	توکن تراکنش	string	اجباری	`f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1`
`amount`	مبلغ (تومان)	integer	اجباری	`74250`
`refund_request`	دستور لغو	string	مقدار اجباری	`yes_money_back`

* مهم : برای لغو تراکنش موفق ، پارامتر refund_request اجباراً فقط و فقط باید دارای مقدار yes_money_back باشد.

پاسخ

پاسخ در قالب json شامل موارد زیر خواهد بود

پارامتر	عنوان	نوع	مثال
`code`	کد وضعیت تراکنش	uuid	`-90`
`amount`	مبلغ (تومان)	integer	`74250`
`order_id`	شماره سفارش	string	`85NX85s427`
`card_holder`	کارت پرداخت کننده	string	`5022-29-**-5020`
`customer_phone`	موبایل پرداخت کننده	numeric	`09121234567`
`custom`	اطلاعات دلخواه	json	`{ "productName":"Shoes752" , "id":52 }`

* نکته : اگر پارامتر code در پاسخ دارای مقدار 90- باشد، یعنی تراکنش (( برگشت خورده )) و لغو است . هر مقداری غیر از 90- به معنی کنسل نشدن تراکنش است.

پیوست 1- کد های وضعیت و خطا

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

کد	توضیح
`0`	پرداخت تکمیل و با موفقیت انجام شده است
`-1`	منتظر ارسال تراکنش و ادامه پرداخت
`-2`	پرداخت رد شده توسط کاربر یا بانک
`-3`	پرداخت در حال انتظار جواب بانک
`-4`	پرداخت لغو شده است
`-20`	کد api_key ارسال نشده است
`-21`	کد trans_id ارسال نشده است
`-22`	مبلغ ارسال نشده
`-23`	لینک ارسال نشده
`-24`	مبلغ صحیح نیست
`-25`	تراکنش قبلا انجام و قابل ارسال نیست
`-26`	مقدار توکن ارسال نشده است
`-27`	شماره سفارش صحیح نیست
`-28`	مقدار فیلد سفارشی [custom_json_fields] از نوع json نیست
`-29`	کد بازگشت مبلغ صحیح نیست
`-30`	مبلغ کمتر از حداقل پرداختی است
`-31`	صندوق کاربری موجود نیست
`-32`	مسیر بازگشت صحیح نیست
`-33`	کلید مجوز دهی صحیح نیست
`-34`	کد تراکنش صحیح نیست
`-35`	ساختار کلید مجوز دهی صحیح نیست
`-36`	شماره سفارش ارسال نشد است
`-37`	شماره تراکنش یافت نشد
`-38`	توکن ارسالی موجود نیست
`-39`	کلید مجوز دهی موجود نیست
`-40`	کلید مجوزدهی مسدود شده است
`-41`	خطا در دریافت پارامتر، شماره شناسایی صحت اعتبار که از بانک ارسال شده موجود نیست
`-42`	سیستم پرداخت دچار مشکل شده است
`-43`	درگاه پرداختی برای انجام درخواست یافت نشد
`-44`	پاسخ دریاف شده از بانک نامعتبر است
`-45`	سیستم پرداخت غیر فعال است
`-46`	درخواست نامعتبر
`-47`	کلید مجوز دهی یافت نشد [حذف شده]
`-48`	نرخ کمیسیون تعیین نشده است
`-49`	تراکنش مورد نظر تکراریست
`-50`	حساب کاربری برای صندوق مالی یافت نشد
`-51`	شناسه کاربری یافت نشد
`-52`	حساب کاربری تایید نشده است
`-60`	ایمیل صحیح نیست
`-61`	کد ملی صحیح نیست
`-62`	کد پستی صحیح نیست
`-63`	آدرس پستی صحیح نیست و یا بیش از ۱۵۰ کارکتر است
`-64`	توضیحات صحیح نیست و یا بیش از ۱۵۰ کارکتر است
`-65`	نام و نام خانوادگی صحیح نیست و یا بیش از ۳۵ کاکتر است
`-66`	تلفن صحیح نیست
`-67`	نام کاربری صحیح نیست یا بیش از ۳۰ کارکتر است
`-68`	نام محصول صحیح نیست و یا بیش از ۳۰ کارکتر است
`-69`	آدرس ارسالی برای بازگشت موفق صحیح نیست و یا بیش از ۱۰۰ کارکتر است
`-70`	آدرس ارسالی برای بازگشت ناموفق صحیح نیست و یا بیش از ۱۰۰ کارکتر است
`-71`	موبایل صحیح نیست
`-72`	بانک پاسخگو نبوده است لطفا با نکست پی تماس بگیرید
`-73`	مسیر بازگشت دارای خطا میباشد یا بسیار طولانیست
`-90`	بازگشت مبلغ بدرستی انجام شد
`-91`	عملیات ناموفق در بازگشت مبلغ
`-92`	در عملیات بازگشت مبلغ خطا رخ داده است
`-93`	موجودی صندوق کاربری برای بازگشت مبلغ کافی نیست
`-94`	کلید بازگشت مبلغ یافت نشد