مستندات فنی

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


به راهنمای سرویس درگاه پرداختی اینترنتی نوینو پی خوش آمدید ؛ این مستندات جهت پیاده سازی سرویس درگاه پرداخت IPG نوینو پی آماده شده است. در صورت بروز هر گونه سوال یا مشکل لطفا با ما در ارتباط باشید.

خواهشمند است قبل از اقدام جهت پیاده سازی نکات ذیل را مطالعه فرمایید
• نوینو از پروتکل https به جهت ایمن سازی ارتباط شبکه استفاده میکند؛ بنابراین تمامی درخواست ها میبایست با این پروتکل ارسال شود.
• تمامی API های نوینو بصورت restful و relational ایجاد شده است.
• تمامی درخواست و پاسخ های API های نوینو بصورت json خواهد بود.
• تمامی واحد های پولی در این مستند ریال میباشد.
• جهت تست میتوانید مقدار مرچنت را test قرارداده و پس از پیاده سازی جهت عملیاتی نمودن سرویس، صرفا مرچنت کدعملیاتی خود را جایگزین نمایید .

فرایند کلی پرداخت
فرایند كلی اتصال به درگاه پرداخت و انجام تراكنش طی 3 فرایند اصلی به شرح موارد ذیل صورت میپذیرد.
1 .درخواست ایجاد تراكنش
2 .بازگشت از درگاه پرداخت
3 .انجام تایید تراكنش

همچنین میتوانید نمونه کد PHP و کالکشن postman مربوط به این مستند را در گیت هاب دریافت نمایید


درخواست ایجاد تراكنش ( Request )
به منظور درخواست ایجاد تراكنش (سشن پرداخت) میبایست پارامتر های زیر را بصورت json در قالب body درخواست و با متد POST به آدرس زیر ارسال فرمایید.
https://api.novinopay.com/payment/ipg/v2/request
پارامتر نوع اجباری شرح
merchant_id string بله مرچنت (کد درگاه پرداخت) كه بعد از ثبت درگاه در پنل نوینو قابل دریافت است
amount integer بله مبلغ قابل پرداخت(ریال) (حداقل مبلغ 10.000 ریال حداكثر مبلغ 500.000.000 ریال)
callback_url string(url)(1000) بله پس از بازگشت خریدار از درگاه پرداخت برخی اطلاعات بصورت POST یا query string (وابسته به مقدار callback_method ) به این آدرس ارسال خواهد شد
callback_method enum(GET, POST) خیر متد جهت فراخوانی آدرس بازگشتی
صرفا مقدار POST یا GET
پیش فرض GET( توصیه میشود)
invoice_id string(255) خیر شماره فاکتور داخلی پذیرنده
description string(255) خیر توضیحات پذیرنده
email string(255) خیر ایمیل خریدار
mobile string(15) خیر تلفن همراه خریدار
(در صورت عدم ارسال؛ آمار تحلیلی پنل کاربری و شماره کارت های ذخیره شده پرداخت کننده نمایش داده نخواهد شد)
name string(255) خیر نام پرداخت کننده
card_pan string(16) خیر شماره کارت پرداخت کننده
16رقم بدون –
جهت الزام پرداخت كننده به پرداخت با كارت مشخص

نمونه json درخواست:
    {
        "merchant_id": "72DFC0B7321D6111-9043-245D-64E9-C81E",
        "amount": 10000,
        "callback_url": "https://YourDomain.com/callback",
        "callback_method": "GET",
        "invoice_id": "order_123456",
        "description": "NovinoPay Test",
        "email": "a@b.com",
        "mobile": "09121234567",
        "name": "ali yari"
    }
                        


لیست داده های برگشتی در پاسخ به فرایند ایجاد تراكنش
پارامتر نوع شرح
status string در صورت موفقیت آمیز بودن برابر 100 در غیر این صورت عددی منفی میباشد كه در صورت منفی بودن, تفسیر آن در كدهای برگشتی / خطاها و پارامتر message قابل برسی می باشد
message string تفسیر فارسی بر اساس status
data object|null object
errors array|null صرفا در حالتی كه status برابر 1 -باشد، در غیر اینصورت برابر null خواهد بود
data (object)
wage کارمزد (ریال)
wage_payer پرداخت کننده کارمزد
(merchant, customer)
authority شناسه دیجیتال تراکنش
trans_id شناسه تراکنش نوینو
payment_url لینک جهت ارجاع کاربر به درگاه
نمونه json پاسخ دریافتی:
{
    "status": "100",
    "message": "عملیات موفقیت آمیز",
    "data": {
        "wage": 0,
        "wage_payer": "merchant",
        "authority": "812F739E41057BAC22331918CD5B41C2",
        "trans_id": 337811,
        "payment_url": "https://ipg.novinopay.com/StartPay/812F739E41057BAC22331918CD5B41C2"
    },
    "errors": null
}
                        


بازگشت از درگاه پرداخت
پس از اتمام فرایند خرید از درگاه پرداخت، خریدار به آدرس callback_url مورد نظر پذیرنده به همراه سه پارامتر PaymentStatus ، Authority و InvoiceID با متد درخواستی در مرحله ایجاد تراكنش (پارامتر callback_method ) هدایت میشود. پذیرنده میابیست مقدار پارامتر PaymentStatus را بررسی نماید؛
1 .در صورتی كه مقداری برابر OK داشته باشد به معنای انجام تراكنش موفق بوده و هم اكنون پذیرنده میابیست نسبت به انجام تاییدیه تراكنش اقدام نماید.
توجه فرمایید:
o حداكثر مهلت زمان جهت دریافت تاییدیه تراكنش 10 دقیقه میباشد در غیر اینصورت تراكنش به حساب خریدار بازگشت خواهد خورد.
o تحویل کالا یا خدمات الزاما میبایست پس از دریافت پاسخ موفق تاییدیه تراكنش صورت پذیرد.

2 .در صورتی كه مقداری برابر NOK داشته باشد پرداخت ناموفق بوده و فرایند تراكنش به اتمام رسیده است



تایید تراکنش ( Verification )

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

پس از دریافت نتیجه اولیه تراكنش موفق (PaymentStatus == OK) الزاما نیاز به انجام تاییدیه تراكنش توسط پذیرنده جهت تکمیل عملیات پرداخت وجود دارد. به منظور دریافت تاییدیه تراكنش میبایست پارامتر های زیر را بصورت json در قالب body درخواست و با متد POST به آدرس زیر ارسال فرمایید.
https://api.novinopay.com/payment/ipg/v2/verification
پارامتر نوع اجباری شرح
merchant_id string بله مرچنت (کد درگاه پرداخت) كه بعد از ثبت درگاه در پنل نوینو قابل دریافت است
amount integer بله مبلغ (ریال)
authority string بله شناسه دیجیتال تراکنش

نمونه json درخواست:
{
    "merchant_id": "72DFC0B7321D6111-9043-245D-64E9-C81E",
    "amount": "10000",
    "authority": "812F739E41057BAC22331918CD5B41C2"
}
                    


لیست داده های برگشتی در پاسخ به فرایند تایید تراكنش
پارامتر نوع شرح
status string در صورت موفقیت آمیز بودن برابر 100 در غیر این صورت عددی منفی میباشد كه در صورت منفی بودن, تفسیر آن در كدهای برگشتی / خطاها و پارامتر message قابل برسی می باشد
message string تفسیر فارسی بر اساس status
data object|null object
errors array|null صرفا در حالتی كه status برابر 1 -باشد، در غیر اینصورت برابر null خواهد بود
data (object)
trans_id شناسه تراکنش نوینو
ref_id شماره پیگیری بانک
authority شناسه دیجیتال تراکنش
card_pan شماره كارت پرداخت كننده بصورت Mask شده
amount مبلغ (ریال)
invoice_id شماره صورتحساب پذیرنده
buyer_ip ای پی پرداخت کننده
payment_time زمان پرداخت (timestamp)
نمونه json پاسخ دریافتی:
{
    "status": "100",
    "message": "عمليات موفق",
    "data": {
        "trans_id": 337811,
        "ref_id": "223003535268",
        "authority": "812F739E41057BAC22331918CD5B41C2",
        "card_pan": "504172******0613",
        "amount": 1000,
        "invoice_id": null,
        "buyer_ip": "5.113.185.222",
        "payment_time": 1663376322
    },
    "errors": null
}
                        


لیست کد خطا
کد خطا
(status)
شرح
100 عملیات موفقیت آمیز
101 عملیات پرداخت موفق بوده و قبلا تاییدیه تراكنش انجام شده است
-1 بروز خطای عمومی - رد درخواست بر اساس اعتبار سنجی اولیه (توضیحات بیشتر در پارامتر errors)
-101 كد پذیرنده وارد شده نامعتبر یا غیرفعال است
-102 ip سرور درخواست دهنده معتبر نمیباشد
-103 آدرس بازگشتی با آدرس درگاه پرداخت ثبت شده همخوانی ندارد
-104 مبلغ ارسال شده صحیح نمیباشد
-105 مجموع مبلغ تراكنش و كارمزد نباید بیش از 500.000.000 ریال باشد
-106 شماره كارت ارسالی معتبر نمیباشد
-107 وبسرویس مقصد جهت اتصال معتبر نمیباشد لطفا با پشتیبانی در ارتباط باشید
-108 بروز خطای سیستمی - ایجاد تراكنش با خطا مواجه شد
-109 مقدار authority معتبر نبوده و یا با كد پذیرنده شما مطابقت ندارد
-110 مبلغ ارسال شده برای تاییدیه با مبلغ تراكنش یکسان نیست
-111 تراكنش در انتظار پرداخت میباشد
-112 تراكنش ناموفق بوده و امکان تایید آن وجود ندارد
-113 مدت زمان تایید تراكنش به اتمام رسیده و مبلغ به حساب پرداخت كننده برگشت خواهد خورد
-114 تراكنش به حساب پرداخت كننده مرجوع شده است
-115 سشن ایجاد شده جهت پرداخت منقضی شده است
-116 بروز خطای بانکی – وریفای تراكنش از سمت بانك رد شد
-117 ارسال شماره كارت جهت پرداخت الزامی میباشد ( در برخی درگاه ها با هماهنگی پشتیبانی نوینو، ارسال شماره كارت الزامی میباشد. )

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