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

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

مقدمه

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

مراحل استفاده از وب سرویس های تسویه و برداشت وجه

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

1- تسویه به شبا از محل موجودی قابل برداشت - کسر کارمزد پایا از مبلغ تسویه

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

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`amount`	مبلغ (تومان)	integer	اجباری	`74250`
`sheba`	شماره شبا - بدون IR	numeric	اجباری	`123456123456123456123456`
`name`	نام صاحب حساب	string	اجباری	`محمد محمدی`
`tracker`	کد یکتای دلخواه	alphanumeric,-,_	اختیاری	`b55-22_33s`
`currency`	واحد پول	string	اختیاری	`IRR` هر مقداری غیر از IRR باعث میشود مبلغ برحسب تومان در نظر گرفته شود

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

2- تسویه به شبا از محل موجودی قابل برداشت - کسر کارمزد پایا از صندوق شما

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

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`amount`	مبلغ (تومان)	integer	اجباری	`74250`
`sheba`	شماره شبا - بدون IR	numeric	اجباری	`123456123456123456123456`
`name`	نام صاحب حساب	string	اجباری	`محمد محمدی`
`tracker`	کد یکتای دلخواه	alphanumeric,-,_	اختیاری	`b55-22_33s`
`currency`	واحد پول	string	اختیاری	`IRR` هر مقداری غیر از IRR باعث میشود مبلغ برحسب تومان در نظر گرفته شود

3- تسویه آنی پیش از موعد به کارت/شبا از محل موجودی کل - کسر کارمزد از صندوق شما

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

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`amount`	مبلغ (تومان)	integer	اجباری	`74250`
`type`	نوع تسویه	string	اجباری	`card` یا `sheba`
`sheba`	شماره شبا - بدون IR	numeric	اجباری (با توجه به نوع تسویه)	`123456123456123456123456`
`card`	شماره 16 رقمی کارت	numeric	اجباری (با توجه به نوع تسویه)	`6219861000001234`
`name`	نام صاحب حساب	string	اجباری	`محمد محمدی`
`tracker`	کد یکتای دلخواه	alphanumeric,-,_	اختیاری	`b55-22_33s`
`currency`	واحد پول	string	اختیاری	`IRR` هر مقداری غیر از IRR باعث میشود مبلغ برحسب تومان در نظر گرفته شود

4- دریافت وضعیت و جزییات یک درخواست تسویه بر اساس کد پیگیری نکست پی یا همان `trace`

در پاسخ تمامی موارد ثبت درخواست تسویه که در بالا گفته شد، پارامتری تحت عنوان trace دریافت میکنید که این پارامتر همان (( کد پیگیری نکست پی )) است. با استفاده از این کد پیگیری و وب سرویسی که در این بخش معرفی شده، میتوانید وضعیت و جزییات تسویه حساب با کد پیگیری مذکور را بررسی کرده و استعلام بگیرید
اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/get_checkout_status

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`checkoutId`	کد پیگیری نکست پی	numeric	اجباری	`95012`

5- دریافت وضعیت و جزییات یک درخواست تسویه بر اساس کد ترکر ارسالی شما یا همان `tracker`

در تمامی انواع درخواست های برداشت وجه، شما میتوانید یک کد پیگیری از نوع UUID یا GUID در سمت خود تولید کرده و پارامتر tracker را در حین ثبت درخواست تسویه ، با استفاده از آن مقدار دهی کنید تا بتوانید درخواست تسویه خود را حتی در صورتی که کد پیگیری نکست پی مربوط به آن را در اختیار نداشته باشید، پیگیری کنید. با استفاده از این کد پیگیری و وب سرویسی که در این بخش معرفی شده، میتوانید وضعیت و جزییات تسویه حساب با کد پیگیری مذکور را بررسی کرده و استعلام بگیرید
اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/get_checkout_status_tracker

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`tracker`	کد tracker شما	alphanumeric,-,_	اجباری	`b11-55_55`

6- دریافت موجودی یک درگاه خاص

با فراخوانی این وب سرویس میتوانید موجودی یک درگاه خاص ( api_key ) را دریافت کنید . موجودی قابل برداشت درگاه مربوطه و موجودی کل آن ، و همچنین مجموع موجودی سایر درگاه های شما و موجودی قابل برداشت کل آن ها را به تفکیک دریافت میکنید.
اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/get_api_balance

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`
`api_key`	کلید مجوز دهی درگاه شما	uuid/guid	اجباری	`b11ee9c3-d23d-414e-8b6e-f2370baac97b`

7- دریافت مجموع موجودی ها و تسویه ها

با فراخوانی این وب سرویس میتوانید موجودی کل، موجودی قابل برداشت ، مجموع تسویه های موفق ، ، در صف و در انتظار را بر حسب ریال و تومان دریافت کنید.
اندپوینت و متد :
POST : https://nextpay.org/nx/gateway/get_balance

پارامتر	عنوان	نوع	ضرورت	مثال
`wid`	شماره وب سرویس شما	integer	اجباری	`32`
`auth`	کد محرمانه وب سرویس	string	اجباری	`7207c1690e3acb95dcd3aafc1ec1ab7a14ca6b8s`

قالب پاسخ تمامی استعلام های بالا

هر کدام از موارد 4 یا 5 یا 6 یا 7 در بالا را فراخوانی کنید در پاسخ ، در فرمت json داده های مورد نیاز را دریافت خواهید کرد. برای بررسی دقیق پاسخ میتوانید از نرم افزار هایی مانند Postman استفاده کنید و پارامتر های کامل پاسخ را مشاهده کنید.

پارامتر	عنوان	نوع	مثال
`code`	وضعیت پردازش درخواست	integer	`200` به معنی درخواست صحیح
`message`	متن پیام پاسخ	string	`Your request has been processed successfully`
`apiTotalBalanceIRT`	موجودی کل درگاه به تومان	integer	`50000`
`apiTotalBalanceIRR`	موجودی کل درگاه به ریال	integer	`500000`
`apiWithdrawableBalanceIRT`	موجودی قابل برداشت درگاه به تومان	integer	`50000`
`apiWithdrawableBalanceIRR`	موجودی قابل برداشت درگاه به ریال	integer	`500000`
`totalBalanceIRT`	موجودی کل به تومان	integer	`50000`
`totalBalanceIRR`	موجودی کل به ریال	integer	`500000`
`withdrawableBalanceIRT`	موجودی قابل برداشت به تومان	integer	`50000`
`withdrawableBalanceIRR`	موجودی قابل برداشت به ریال	integer	`500000`
`notificationWalletIRT`	موجودی کیف پول پیامکی به تومان	integer	`2000`
`notificationWalletIRR`	موجودی کیف پول پیامکی به ریال	integer	`20000`
`inQueueCheckoutsIRT`	تسویه های در صف به تومان	integer	`0`
`inQueueCheckoutsIRR`	تسویه های در صف به ریال	integer	`0`
`inProcessCheckoutsIRT`	تسویه های در حال پردازش به تومان	integer	`0`
`inProcessCheckoutsIRR`	تسویه های در حال پردازش به ریال	integer	`0`
`completedCheckoutsIRT`	تسویه های انجام شده به تومان	integer	`5000`
`completedCheckoutsIRR`	تسویه های انجام شده به ریال	integer	`50000`
`checkoutId`	کد پیگیری نکست پی	numeric	`95012`
`checkoutAmountIRT`	مبلغ تسویه به تومان	integer	`5000`
`checkoutAmountIRR`	مبلغ تسویه به ریال	integer	`50000`
`feeIRT`	کارمزد تسویه به تومان	integer	`200`
`feeIRR`	کارمزد تسویه به ریال	integer	`2000`
`destination`	شبا یا کارت مقصد	string	`020570077700150058177501`
`trackingNumber`	کد پیگیری بانک	string	`14000423056203152106`
`status`	وضعیت	string	`Completed`
`statusDescription`	شرح وضعیت	string	`Your withdrawal request has been completed`
`tracker`	کد یکتای دلخواه شما	alphanumeric,-,_	`b55-22_33s`
`requestedAt`	زمان درخواست	string	`1400-04-23 18:15:24`
`updatedAt`	زمان بروزرسانی وضعیت	string	`1400-04-23 18:15:25`