آیا میتوانم از نمونه کد های مستندات نوینو پی استفاده کنم؟

بله شما میتوانید تمامی نمونه کد های اتصال به وبسرویس نوینو پی را در گیت هاب دریافت نمایید

مستندات و نمونه کدها

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

به راهنمای سرویس درگاه پرداختی اینترنتی نوینو پی خوش آمدید ؛ این مستندات جهت پیاده سازی سرویس درگاه پرداخت 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 ریال حداكثر مبلغ 1.000.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`	مجموع مبلغ تراكنش و كارمزد نباید بیش از 1.000.000.000 ریال باشد
`-106`	شماره كارت ارسالی معتبر نمیباشد
`-107`	وبسرویس مقصد جهت اتصال معتبر نمیباشد لطفا با پشتیبانی در ارتباط باشید
`-108`	بروز خطای سیستمی - ایجاد تراكنش با خطا مواجه شد
`-109`	مقدار authority معتبر نبوده و یا با كد پذیرنده شما مطابقت ندارد
`-110`	مبلغ ارسال شده برای تاییدیه با مبلغ تراكنش یکسان نیست
`-111`	تراكنش در انتظار پرداخت میباشد
`-112`	تراكنش ناموفق بوده و امکان تایید آن وجود ندارد
`-113`	مدت زمان تایید تراكنش به اتمام رسیده و مبلغ به حساب پرداخت كننده برگشت خواهد خورد
`-114`	تراكنش به حساب پرداخت كننده مرجوع شده است
`-115`	سشن ایجاد شده جهت پرداخت منقضی شده است
`-116`	بروز خطای بانکی – وریفای تراكنش از سمت بانك رد شد
`-117`	ارسال شماره كارت جهت پرداخت الزامی میباشد ( در برخی درگاه ها با هماهنگی پشتیبانی نوینو، ارسال شماره كارت الزامی میباشد. )