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 }
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 کد وضعیت تراکنش 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 باشد ، یعنی عملیات با موفقیت انجام شده و درخواست شما ثبت شده است. در غیر اینصورت درخواست شامل خطا بوده است .