مقدمه

    API Endpoints

        https://api.novinpal.ir/invoice/request
        https://api.novinpal.ir/invoice/start/{{refId}}
        https://api.novinpal.ir/invoice/verify
        https://api.novinpal.ir/invoice/reverse
        

به راهنمای سرویس درگاه پرداختی اینترنتی (IPG) نوین‌پال خوش آمدید. این مستندات جهت آسانی استفاده شما از سرویس‌های نوین‌پال جمع آوری شده‌اند. در صورت بروز هر گونه سوال با تیم فنی نوین‌پال تماس بگیرید. وظیفه همکاران ما پاسخ به پیام‌های شما در اسرع وقت است.

لطفا قبل از پیاده‌سازی به نکات زیر توجه نمایید:

• API های نوین‌پال RESTful می‌باشند و درخواست‌ها و پاسخ‌ها به صورت Form-Data رد و بدل می‌شوند.
• نوین‌پال تنها به درخواست‌هایی که تحت دامنه معرفی شده از طرف پذیرنده ارسال می‌شوند پاسخ خواهد داد.
• در صورت دریافت هرگونه خطا از جانب نوین‌پال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط نوین‌پال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!

دانلود نمونه کالکشن پست من نوین پال novinpal.postman_collection.json

مراحل راه‌اندازی

استفاده و راه‌اندازی سرویس درگاه پرداخت اینترنتی نوین‌پال پیچیده نیست. تنها کافیست سه مرحله زیر را به‌درستی پیاده کنید!

1. درخواست پرداخت - Request

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

2. شروع پرداخت - Start

با ارسال refId به این پایانه صفحه‌ی پرداخت برای شما نمایان می‌شود و شما آماده‌ی پرداخت هستید.

3. تأیید پرداخت - Verify

نوین‌پال وضعیت پرداخت هر سفارش را به آدرس return_url ای که برای آن سفارش ثبت کرده‌اید ارسال می‌کند. پس از آن نیاز است که شما متد تایید تراکنش را فرخوانی کنید. تایید موفقیت‌آمیز بودن پرداخت از طریق این پایانه میسر است.

با طی شدن مسیر ذکر شده روند پرداخت یک سفارش پایان می‌یابد. مبلغ واریزی از طریق درگاه پرداخت اینترنتی بسته به تنظیمات حساب کاربری شما به حساب تعیین‌شده توسط شما واریز می شود.

درخواست پرداخت - Request

از این پایانه جهت ارسال اطلاعات سفارش و ثبت آن در سیستم نوین‌پال استفاده کنید.

اطلاعات درخواست

POST https://api.novinpal.ir/invoice/request

بدنه درخواست

POST
https://api.novinpal.ir/invoice/request
{
    "api_key": "xxxxxxxxxxxxxxxxxxxx",
    "amount": 10000,
    "return_url": "http://yourapiurl.com/callback.php",
    "order_id": "NP-88999",
    "description": "Sample description",
    "mobile": "09129999999",
    "card_number": "610433******2024
}
                

پارامتر	ضروری؟	نوع	توضیحات
api_key	بله	رشته (String)	کلید API شما
amount	بله	عدد (Long)	مبلغ کل سفارش (به ریال)
return_url	بله	رشته (String)	آدرسی از سایت پذیرنده که نوین‌پال اطلاعات پرداخت را به آن ارسال خواهد کرد.
order_id	بله	رشته (String)	شناسه سفارش منحصربه‌فرد شما
description	خیر	رشته (String)	توضیحات مربوط به سفارش
mobile	خیر	رشته (String)	با فرستادن شماره موبایل کاربران خود، شماره کارت‌های ثبت‌شده مشتریان در درگاه پرداخت جهت انتخاب ظاهر می‌شوند.
card_number	خیر	رشته (String)	در صورت نیاز به احراز هویت پرداخت کننده (تطبیق کارت پرداخت کننده با کارت ارسالی از سوی شما)
توجه: شماره کارت باید کامل و صحیح ارسال شود در غیر اینصورت پرداخت تایید نمی‌شود

بدنه پاسخ

در صورت موفقیت آمیز بودن

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

{
    "refId":  "447515262",
    "status": 1,
}
                

در صورت رد درخواست

در صورت رد پاسخی حاوی کد وضعیت، کد خطا و شرح خطا بازگردانده خواهد شد.

{
    "status": 0,
    "errorCode": 103,
    "errorDescription" : "return url is invalid"
}
                

جدول status

کد	توضیحات
1	تأیید درخواست
0	رد درخواست

جدول errorCode

کد	توضیحات
100	درخواست موفقیت آمیز بود
101	آی پی سایت پذیرنده مجاز نیست
102	ترمینال بلاک شده است
103	آدرس بازگشتی متعلق به سایت پذیرنده نیست
104	خطای PSP
107	PSP یافت نشد
108	خطای سرور
110	مبلغ اشتباه وارد شده یا کمتر از 10000 ریال است
111	کلید API اشتباه است
112	پذیرنده غیرفعال است
114	متد ارسال شده اشتباه است
115	ترمینال تأیید نشده است
116	ترمینال غیرفعال است
117	ترمینال رد شده است
118	ترمینال تعلیق شده است
119	ترمینالی تعریف نشده است
120	حساب کاربری پذیرنده به حالت تعلیق درآمده است
121	حساب کاربری پذیرنده تأیید نشده است
122	حساب کاربری پذیرنده یافت نشد
123	کارت نامعتبر است (عدم تطبیق کارت ارسالی با کارت پرداختی)

شروع پرداخت - Start

از این پایانه جهت ورود به صفحه‌ی پرداخت و شروع پرداخت استفاده کنید.

اطلاعات درخواست

GET https://api.novinpal.ir/invoice/start/{{refId}}

بدنه درخواست

با ارسال refId به آدرس بالا و باز کردن این صفحه در مرورگر به صفحه‌ی پرداخت منتقل خواهید شد.

پاسخ - Callback

نوین‌پال اطلاعات پرداخت یک سفارش را در زمان تغییر وضعیت به return_url ثبت شده برای آن سفارش ارسال می‌کند.

این اطلاعات به صورت Query String و از طریق متد GET برای return_url ارسال می‌شوند.

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

بدنه Callback

پارامتر	توضیحات
success	در صورت موفقیت آمیز بودن تراکنش 1، در غیر این صورت 0 است
refId	شناسه مرجع جلسه‌ی پرداخت
code	کد وضعیت پرداخت
invoiceNumber	شناسه سفارش ارسال شده در هنگام درخواست پرداخت
amount	مبلغ تراکنش

مثال

https://return-url.com/callback?refId=999999&success=1&code=100&invoiceNumber=888888&amount=10000

جدول code

کد	توضیحات
100	تراکنش موفقیت آمیز بود
109	تراکنش ناموفق بود
104	خطای PSP
107	PSP یافت نشد
108	خطای سرور
114	متد ارسال شده اشتباه است
115	ترمینال تأیید نشده است
116	ترمینال غیرفعال است
117	ترمینال رد شده است
118	ترمینال تعلیق شده است
119	ترمینالی تعریف نشده است
120	حساب کاربری پذیرنده به حالت تعلیق درآمده است
121	حساب کاربری پذیرنده تأیید نشده است
122	حساب کاربری پذیرنده یافت نشد

تأیید پرداخت - Verify

از این پایانه جهت تایید موفقیت‌آمیز بودن پرداخت و پایان دادن به یک جلسه‌ی پرداخت استفاده نمایید.

تایید پرداخت

همان‌طور که قبلا اشاره شد نوین‌پال با ارسال اطلاعات پرداخت به return_url ثبت‌شده، شما را از وضعیت یک پرداخت مطلع می‌سازد. این پایانه جهت اطمینان نوین‌پال از دریافت این اطلاعات توسط شما و خاتمه‌دادن پروسه پرداخت سفارش تعبیه شده‌است.

اطلاعات درخواست

POST https://api.novinpal.ir/invoice/verify

بدنه درخواست

POST
https://api.novinpal.ir/invoice/verify
{
    "api_key": "xxxxxxxxxxxxxxxxxxxx",
    "ref_id": 99999999,
}
                

پارامتر	ضروری؟	نوع	توضیحات
api_key	بله	رشته (String)	کلید API شما
ref_id	بله	رشته (String)	شناسه مرجع سفارش که در بدنه پاسخ به "درخواست پرداخت - Request" برای شما ارسال می شود

بدنه پاسخ

در صورت موفقیت آمیز بودن

در صورت صحت اطلاعات ارسالی پاسخی حاوی اطلاعات تراکنش بازگردانده خواهد شد.

{
    "paidAt":  "2022-12-07 19:59:45",
    "cardNumber": "6104-33**-****-6047",
    "status": 1,
    "amount": 10000,
    "refNumber": "638060399619297999",
    "refId": "509744199",
    "description": "Sample description",
    "orderId": "9999999",
    "verifiedBefore": false,
}
                

پارامتر	توضیحات
paidAt	تاریخ پرداخت سفارش (در صورت موفقیت‌آمیز بودن پرداخت)
cardNumber	شماره کارت پرداخت کننده (Mask شده)
status	وضعیت پرداخت
amount	مبلغ سفارش (به ریال)
refNumber	شناسه مرجع بانکی تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
refId	شناسه مرجع تراکنش نزد نوین‌پال
description	توضیحات تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
orderId	شناسه سفارش (در صورت موفقیت‌آمیز بودن پرداخت)
verifiedBefore	در صورتی که تراکنش قبلاً توسط شما تأیید شده باشد این مقدار true برگردانده خواهد شد

جدول status

کد	توضیحات
1	تراکنش موفقیت آمیز بوده است
0	در انتظار پرداخت
-1	تراکنش ناموفق بوده است
-2	خطای سرور

در صورت رد درخواست

در صورت رد درخواست، پاسخی حاوی کد وضعیت، کد خطا و شرح خطا بازگردانده خواهد شد.

{
    "status": 0,
    "errorCode": 101,
    "errorDescription" : "access denied"
}
                

جدول errorCode

کد	توضیحات
100	درخواست موفقیت آمیز بود
101	آی پی سایت پذیرنده مجاز نیست
102	ترمینال بلاک شده است
103	آدرس بازگشتی متعلق به سایت پذیرنده نیست
104	خطای PSP
107	PSP یافت نشد
108	خطای سرور
110	مبلغ اشتباه وارد شده یا کمتر از 10000 ریال است
111	کلید API اشتباه است
112	پذیرنده غیرفعال است
114	متد ارسال شده اشتباه است
115	ترمینال تأیید نشده است
116	ترمینال غیرفعال است
117	ترمینال رد شده است
118	ترمینال تعلیق شده است
119	ترمینالی تعریف نشده است
120	حساب کاربری پذیرنده به حالت تعلیق درآمده است
121	حساب کاربری پذیرنده تأیید نشده است
122	حساب کاربری پذیرنده یافت نشد

برگشت وجه تراکنش - Reverse

از این پایانه جهت برگشت وجه یک تراکنش موفق (Reverse) تا حداکثر 120 دقیقه پس از تراکنش استفاده نمایید.

برگشت تراکنش

در نوین پال می توانید بنا به هر دلیلی تراکنش و پرداختی موفق مشتریان خود را با عملیات Reverse لغو و به صورت خودکار وجه پرداختی آن ها را عودت دهید. توجه فرمایید که این عمل می بایست حداکثر تا 120 دقیقه (2 ساعت) پس از تراکنش و پس از وریفای کردن تراکنش صورت بپذیرد.

اطلاعات درخواست

POST https://api.novinpal.ir/invoice/reverse

بدنه درخواست

POST
https://api.novinpal.ir/invoice/reverse
{
    "api_key": "xxxxxxxxxxxxxxxxxxxx",
    "ref_id": 99999999,
}
                

پارامتر	ضروری؟	نوع	توضیحات
api_key	بله	رشته (String)	کلید API شما
ref_id	بله	رشته (String)	شناسه مرجع سفارش که در بدنه پاسخ به "درخواست پرداخت - Request" برای شما ارسال می شود

بدنه پاسخ

در صورت موفقیت آمیز بودن

در صورت صحت اطلاعات ارسالی پاسخی حاوی اطلاعات تراکنش بازگردانده خواهد شد.

{
    "paidAt":  "2022-12-07 19:59:45",
    "cardNumber": "6104-33**-****-6047",
    "status": 1,
    "amount": 10000,
    "refNumber": "638060399619297999",
    "refId": "509744199",
    "description": "Sample description",
    "orderId": "9999999",
    "verifiedBefore": false,
}
                

پارامتر	توضیحات
paidAt	تاریخ پرداخت سفارش (در صورت موفقیت‌آمیز بودن پرداخت)
cardNumber	شماره کارت پرداخت کننده (Mask شده)
status	وضعیت پرداخت
amount	مبلغ سفارش (به ریال)
refNumber	شناسه مرجع بانکی تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
refId	شناسه مرجع تراکنش نزد نوین‌پال
description	توضیحات تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
orderId	شناسه سفارش (در صورت موفقیت‌آمیز بودن پرداخت)
verifiedBefore	در صورتی که تراکنش قبلاً توسط شما تأیید شده باشد این مقدار true برگردانده خواهد شد

جدول status

کد	توضیحات
1	تراکنش موفقیت آمیز بوده است
0	در انتظار پرداخت
-1	تراکنش ناموفق بوده است
-2	خطای سرور

در صورت رد درخواست

در صورت رد درخواست، پاسخی حاوی کد وضعیت، کد خطا و شرح خطا بازگردانده خواهد شد.

            {
                "status": 0,
                "errorCode": 101,
                "errorDescription" : "access denied"
            }
                

جدول errorCode

کد	توضیحات
100	درخواست موفقیت آمیز بود
101	آی پی سایت پذیرنده مجاز نیست
102	ترمینال بلاک شده است
103	آدرس بازگشتی متعلق به سایت پذیرنده نیست
104	خطای PSP
107	PSP یافت نشد
108	خطای سرور
110	مبلغ اشتباه وارد شده یا کمتر از 10000 ریال است
111	کلید API اشتباه است
112	پذیرنده غیرفعال است
114	متد ارسال شده اشتباه است
115	ترمینال تأیید نشده است
116	ترمینال غیرفعال است
117	ترمینال رد شده است
118	ترمینال تعلیق شده است
119	ترمینالی تعریف نشده است
120	حساب کاربری پذیرنده به حالت تعلیق درآمده است
121	حساب کاربری پذیرنده تأیید نشده است
122	حساب کاربری پذیرنده یافت نشد

جدول وضعیت ها

کد	توضیحات
100	درخواست موفقیت آمیز بود
101	آی پی سایت پذیرنده مجاز نیست
102	ترمینال بلاک شده است
103	آدرس بازگشتی متعلق به سایت پذیرنده نیست
104	خطای PSP
105	تراکنش یافت نشد
106	شناسه مرجع اشتباه است
107	PSP یافت نشد
108	خطای سرور
109	تراکنش ناموفق بوده است
110	مبلغ اشتباه وارد شده یا کمتر از 10000 ریال است
111	کلید API اشتباه است
112	پذیرنده غیرفعال است
113	شناسه سفارش اشتباه است
114	متد ارسال شده اشتباه است
115	ترمینال تأیید نشده است
116	ترمینال غیرفعال است
117	ترمینال رد شده است
118	ترمینال تعلیق شده است
119	ترمینالی تعریف نشده است
120	حساب کاربری پذیرنده به حالت تعلیق درآمده است
121	حساب کاربری پذیرنده تأیید نشده است
122	حساب کاربری پذیرنده یافت نشد
123	کارت نامعتبر است (عدم تطبیق کارت ارسالی با کارت پرداختی)

تست API

کلید API

شناسه سفارش

مبلغ (ریال)

آدرس بازگشتی

شماره موبایل (اختیاری)

شماره کارت (اختیاری)

توضیحات (اختیاری)

خطا

لینک پرداخت:

ارسال