Logo

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


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

مقدمه

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

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

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

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

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

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

راهنمای وب سرویس تسویه حساب ( تسهیم / برداشت وجه ) :
CheckOut 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 }
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 توکن تراکنش string اجباری f7c07568-c6d1-4bee-87b1-4a9e5ed2e4c1
amount مبلغ (تومان) integer اجباری 74250

پاسخ


پاسخ در قالب json شامل موارد زیر خواهد بود
پارامتر عنوان نوع مثال
code کد وضعیت تراکنش uuid 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 }
* نکته : اگر پارامتر code در پاسخ دارای مقدار 0 باشد، یعنی تراکنش (( موفق )) بوده است . هر مقداری غیر از صفر به معنی ناموفق بودن تراکنش است.



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


ممکن است به هر دلیلی شما بخواهید یک تراکنش موفق را (( عودت )) دهید و آنرا لغو کنید تا به حساب پرداخت کننده برگردد . دقت فرمایید که برای عودت یک تراکنش موفق ، باید پارامتر های زیر را از طریق متد 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 کلید بازگشت مبلغ یافت نشد





وب سرویس تسویه حساب ، برداشت وجه و تسهیم


برای استفاده از این وب سرویس ابتدا باید با مراجعه به پنل کاربری خود در نکست پی ، در بخش (( برداشت وجه و تسهیم )) ، قسمت (( وب سرویس تسهیم )) آنرا فعال کرده باشید و کد هایauth و wid را در اختیار داشته باشید

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

پارامتر عنوان نوع مثال
wid شماره وب سرویس شما integer 32
auth کد محرمانه وب سرویس string 7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s
amount مبلغ (تومان) integer 74250
sheba شماره شبا - بدون IR numeric 123456123456123456123456
name نام صاحب حساب string محمد محمدی
نکته : با توجه به اینکه تسویه حساب به شکل پایا ثبت میشود و شامل کارمزد پایا میباشد ، از مبلغی که در پارامتر amount ارسال میکنید ، ابتدا کارمزد پایا کسر میشود و مابقی به حساب مقصد واریز میشود .
اگر میخواهید مبلغ amount دقیقاً واریز شود و کارمزد از صندوق شما کسر شود . کافیست همین پارامترها را به اندپوینت دیگری به آدرس https://nextpay.org/nx/gateway/checkout_withoutfee ارسال کنید . در این صورت amount عیناً به حساب مقصد واریز میشود و کارمزد از صندوق شما کسر میشود .

پاسخ : پاسخ در قالب json می باشد و دارای 2 پارامتر code و message است . اگر مقدار code برابر با 200 باشد ، یعنی عملیات با موفقیت انجام شده و درخواست شما ثبت شده است. در غیر اینصورت درخواست شامل خطا بوده است .