Introduction
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
Welcome to Novinpal Internet Payment Gateway (IPG) service guide. These documents have been collected for your ease of using Novinpal services. If you have any questions, contact Novinpal's technical team. The duty of our colleagues is to answer your messages as soon as possible.
Please pay attention to the following points before implementation:
- Novinpal APIs are RESTful and requests and responses are exchanged as Form-Data.
- NovinPal will only respond to requests sent under the nominated domain from the recipient.
- If you receive any error from Novinpal, after checking your sent values, send us this error along with the sent values and the received response values. We are aware of the possibility of error by Novinpal and we will quickly take steps to solve the problem!
Download a sample of Novin Pal's postman collection novinpal.postman_collection.json
Setup steps
It is not complicated to use and set up the Novinpal internet payment gateway service. Just follow the three steps below!
1. Payment request - Request
To set up your portal, Novinpal needs your order information, which can be sent through this terminal. In response, refIdyou will receive this terminal as the payment reference ID.
2. Start payment - Start
By sending refIdto this terminal, the payment page will appear for you and you are ready to pay.
3. Payment confirmation - Verify
Novinpal will send the payment status of each order to the address you return_urlhave registered for that order. After that, you need to call the transaction confirmation method. It is possible to confirm the successful payment through this terminal.
By following the mentioned path, the payment process of an order ends. The deposit amount is deposited through the internet payment portal to the account designated by you depending on your user account settings.
Payment request - Request
Use this terminal to send order information and register it in Novinpal system.
Application information
POST https://api.novinpal.ir/invoice/request
The body of the 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
}
| parameter | Necessary? | type | Description | |
|---|---|---|---|---|
| api_key | Yes | String | Your API key | |
| amount | Yes | Number (Long) | The total amount of the order (in Rials) | |
| return_url | Yes | String | The address of the receiving site to which Novinpal will send the payment information. | |
| order_id | Yes | String | Your unique order ID | |
| description | no | String | Description of the order | |
| mobile | no | 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 | Transaction bank reference ID (if the payment is successful) |
| refId | Transaction reference ID with Novinpal |
| description | Transaction description (if the payment is successful) |
| orderId | Order ID (if payment is successful) |
| verifiedBefore | This value will be returned true if the transaction has already been approved by you |
Tablestatus
| code | Description |
|---|---|
| 1 | The transaction has been successful |
| 0 | Awaiting Payment |
| -1 | The transaction has failed |
| -2 | Server error |
If the request is rejected
If the request is rejected, a response containing the status code, error code and error description will be returned.
{
"status": 0,
"errorCode": 101,
"errorDescription" : "access denied"
}
TableerrorCode
| code | Description |
|---|---|
| 100 | The request was successful |
| 101 | The IP of the receiving site is not allowed |
| 102 | The terminal is blocked |
| 103 | The return address does not belong to the receiving site |
| 104 | PSP error |
| 107 | PSP not found |
| 108 | Server error |
| 110 | The amount entered is incorrect or less than 10,000 Rials |
| 111 | The API key is incorrect |
| 112 | Receiver is inactive |
| 114 | The submitted method is incorrect |
| 115 | The terminal is not verified |
| 116 | The terminal is disabled |
| 117 | The terminal is rejected |
| 118 | The terminal is suspended |
| 119 | The terminal is not defined |
| 120 | The recipient's account has been suspended |
| 121 | The recipient's account has not been verified |
| 122 | Accepting user account not found |
Return of the transaction amount - Reverse
Use this terminal to reverse a successful transaction up to 120 minutes after the transaction.
Transaction reversal
In Novin Pal, for any reason, you can cancel the successful transaction and payment of your customers with the Reverse operation and automatically return their payment. Please note that this action should
120 دقیقه (2 ساعت)
be done at the latest after the transaction and after verifying the transaction.
Application information
POST https://api.novinpal.ir/invoice/reverse
The body of the request
POST
https://api.novinpal.ir/invoice/reverse
{
"api_key": "xxxxxxxxxxxxxxxxxxxx",
"ref_id": 99999999,
}
| parameter | Necessary? | type | Description |
|---|---|---|---|
| api_key | Yes | String | Your API key |
| ref_id | Yes | String | The reference ID of the order that is sent to you in the body of the response to "Request for payment - Request". |
Response body
If successful
If the information sent is correct, a response containing the transaction information will be returned.
{
"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,
}
| parameter | Description |
|---|---|
| paidAt | Order payment date (if the payment is successful) |
| cardNumber | Payer card number (masked) |
| status | Payment status |
| amount | Order amount (in Rials) |
| refNumber | Transaction bank reference ID (if the payment is successful) |
| refId | Transaction reference ID with Novinpal |
| description | Transaction description (if the payment is successful) |
| orderId | Order ID (if payment is successful) |
| verifiedBefore | This value will be returned true if the transaction has already been approved by you |
Tablestatus
| code | Description |
|---|---|
| 1 | The transaction has been successful |
| 0 | Awaiting Payment |
| -1 | The transaction has failed |
| -2 | Server error |
If the request is rejected
If the request is rejected, a response containing the status code, error code and error description will be returned.
{
"status": 0,
"errorCode": 101,
"errorDescription" : "access denied"
}
TableerrorCode
| code | Description |
|---|---|
| 100 | The request was successful |
| 101 | The IP of the receiving site is not allowed |
| 102 | The terminal is blocked |
| 103 | The return address does not belong to the receiving site |
| 104 | PSP error |
| 107 | PSP not found |
| 108 | Server error |
| 110 | The amount entered is incorrect or less than 10,000 Rials |
| 111 | The API key is incorrect |
| 112 | Receiver is inactive |
| 114 | The submitted method is incorrect |
| 115 | The terminal is not verified |
| 116 | The terminal is disabled |
| 117 | The terminal is rejected |
| 118 | The terminal is suspended |
| 119 | The terminal is not defined |
| 120 | The recipient's account has been suspended |
| 121 | The recipient's account has not been verified |
| 122 | Accepting user account not found |
Status table
| code | Description |
|---|---|
| 100 | The request was successful |
| 101 | The IP of the receiving site is not allowed |
| 102 | The terminal is blocked |
| 103 | The return address does not belong to the receiving site |
| 104 | PSP error |
| 105 | Transaction not found |
| 106 | The reference ID is incorrect |
| 107 | PSP not found |
| 108 | Server error |
| 109 | The transaction has failed |
| 110 | The amount entered is incorrect or less than 10,000 Rials |
| 111 | The API key is incorrect |
| 112 | Receiver is inactive |
| 113 | The order ID is incorrect |
| 114 | The submitted method is incorrect |
| 115 | The terminal is not verified |
| 116 | The terminal is disabled |
| 117 | The terminal is rejected |
| 118 | The terminal is suspended |
| 119 | The terminal is not defined |
| 120 | The recipient's account has been suspended |
| 121 | The recipient's account has not been verified |
| 122 | Accepting user account not found |
| 123 | The card is invalid (failure to match the sent card with the payment card) |