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


کلیه درخواست های ایجاد و شروع تراکنش باید به آدرس https://api.novinopay.com/Payment/rest/v1/Request و کلیه درخواست های برسی وضعیت و Verify کردن تراکنش به آدرس https://api.novinopay.com/Payment/rest/v1/Verification ارسال شوند, لذا در کد نویسی دقت داشته باشید آدرس وب سرویس RestFul به شکل زیر خواهد بود :

Payment Request :
https://api.novinopay.com/Payment/rest/v1/Request
Payment Verify :
https://api.novinopay.com/Payment/rest/v1/Verification


فرايند خريد ( Request )

سایت مبدا براي ایجاد و شروع تراکنش باید با توجه به جدول زیر, اطلاعات و دیتاهای مورد نیاز را به آدرس و با متد POST ارسال نماید

https://api.novinopay.com/Payment/rest/v1/Request
پارامتر نوع وضعیت شرح
MerchantID string اجباری مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Amount integer اجباری مبلغی که در تراکنش ارسال و قابل پرداخت میباشد, واحد مبلغ ارسالی تومان و حداقل مبلغ 100 تومان میباشد
InvoiceID string اختیاری شناسه, این شناسه پس از پرداخت برای سایت فروشنده ارسال خواهد شد
Description string اختیاری توضيحات مربوط تراكنش
Email string اختیاری آدرس ایمیل خریدار
Mobile string اختیاری شماره تماس خریدار
CallbackURL string اجباری صفحه بازگشت مشتري، پس از انجام عمل پرداخت

لیست داده هاي برگشتی در پاسخ به فرايند خريد ( Request )
پارامتر شرح
Status وضعيت درخواست كه در صورت موفقيت آميز بودن برابر 100 در غير اين صورت عددي منفي ميباشد که در صورت منفی بودن, تفصیر آن در تب کدهای برگشتی / خطا‌ها قابل برسی می باشد
Authority شناسه مرجع درخواست، درصورت موفق بودن داراي طوال 32 كاراكتر و در غير اينصورت خالي ميباشد
PaymentUrl لینکی که کاربر به منظور پرداخت باید به آن انتقال داده شود

در صورت صحت داده ها نوینو پرداخت یک داده از نوع string به طول 32 کاراکتر (PaymentUrl) و یک داده با نام Status برابر 100 بر می گرداند و سایت پذیرنده پس از دریافت این داده ها، میبایست کاربر را به url مشخص شده در پارامتر PaymentUrl هدایت نماید, توجه داشته باشید که در داده های برگشتی در صورتی که مقدار Status برابر با 100 نباشد, برابر با یک عدد منفی خواهد بود که شرح خطاهای هر عدد منفی را در تب کدهای برگشتی / خطاها مشاهده کنید.

بعد از پايان عمليات درسمت نوینو پرداخت، نوینو پرداخت وظيفه دارد كاربر را به سايت پذيرنده كه از طريق CallbackURL مشخص شده است بازگرداند.


نمونه کد PHP ایجاد شناسه ی پرداخت ( Authority ) و ارجاع کاربر به درگاه پرداخت
<?php

$data = [
    "MerchantID" => "xxxx-xxx-xxxxxxxxxxxx-xxxxxxxxxx",
    "Amount" => 500000,
    "InvoiceID" => "PF-123456",
    "Description" => "Invoice Description",
    "Name" => "Ali Ahmadi",
    "Mobile" => "09120001234",
    "Email" => "info@example.com",
    "CallbackURL" => "https://YourSite.com/Callback"
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.novinopay.com/Payment/rest/v1/Request");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["Content-Type" => "application/json"]);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
curl_setopt($curl, CURLOPT_TIMEOUT, 50);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_exec = curl_exec($curl);
curl_close($curl);

$result = json_decode($curl_exec);

if (isset($result->Status) && $result->Status == 100) {
    header("Location: {$result->PaymentUrl}");
} else {
    echo isset($result->Status) ? "Error Code: {$result->Status} | {$result->Message}" : "Error Connecting to novinopay.com";
}

?>


فرایند برسی وضعیت و نتیجه تراکنش ( Callback / Verify )

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

در صفحه CallbackURL پذيرنده وظيفه دارد درخواست معادل با Authority و PaymentStatus كه از طـرف نوینو پرداخت و بـه صـورت POST به آدرس CallbackURL ارسال شده است را دریافت نموده و در صورتی که مقدار PaymentStatus دریافت شده برابر با " OK " بود, داده‌های جدول زیر را از طریق متـد POST به آدرس https://api.novinopay.com/Payment/rest/v1/Verification ارسال نموده و پاسخ دریافتی را چـك نمايد و در صورت موفق بودن، پرداخت را ثبت و شماره تراكنش را به كاربر خريدار نمايش دهد ؛ در غير اينصورت پذيرنده موظف اسـت كـه بـا توجه به كد خطايي كه دريافت ميكند كاربر را از خطاي رخ داده مطلع سازد. همچنین توجه داشته باشید در صورتی PaymentStatus برابر با " NOK " باشد, تراکنش ناموفق بوده و نیازی به ارسال درخواست Verification نیست.

براي Verify کردن تراکنش باید اطلاعات و دیتاهای مورد نیاز را طبق جدول زیر به آدرس

https://api.novinopay.com/Payment/rest/v1/Verification
از طریق متد POST ارسال کند

پارامتر نوع وضعیت شرح
MerchantID string اجباری مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Authority string اجباری كد يكتاي شناسه مرجع درخواست
Amount integer اجباری مبلغ فاکتور به تومان - مبلغ ارسالی باید با مبلغ اولیه فاکتور در زمان ایجاد تراکنش یکسان باشد

لیست داده هاي برگشتی در پاسخ به فرايند استعلام تراکنش ( Verify )
پارامتر شرح
Status وضعيت درخواست كه در صورت موفقيت آميز بودن برابر 100 در غير اين صورت عددي منفي ميباشد که در صورت منفی بودن, تفصیر آن در تب کدهای برگشتی / خطا‌ها قابل برسی می باشد
RefID در صورتي كه پرداخت موفق باشد؛ شماره تراكنش داخلی پرداخت انجام شده را بر ميگرداند
BankRRN شماره مرجع(rrn) دریافتی از psp
Amount در صورتي كه پرداخت موفق باشد؛ مبلغ پرداخت شده ( مبلغ به تومان می باشد ) را بر میگرداند
BuyerIP در صورتي كه پرداخت موفق باشد؛ IP خریدار را بر میگرداند
PaymentTime در صورتي كه پرداخت موفق باشد؛ زمان پرداخت تراکنش ( خروجی زمان پرداخت به صورت timestamp می باشد ) را بر میگرداند
MaskCardNumber در صورتي كه پرداخت موفق باشد؛ شماره کارت Mask شده خریدار ( شماره کارتی که پرداخت وجه توسط آن انجام شده است ) را بر میگرداند

در صورتی که مقدار بازگشتی Status در فرایند استعلام تراکنش از طریق Verification برابر با 100 باشد تراکنش بدرستی انجام شده است در غیر اینصورت مقدار بازگشتی برابر با یک عدد منفی خواهد بود که شرح خطاهای مرتبط با هر عدد منفی بازگشتی را میتوانید در تب کدهای برگشتی / خطاها برسی کنید.


نمونه کد Callback و Verify کردن تراکنش
<?php

if (isset($_POST["PaymentStatus"]) && $_POST["PaymentStatus"] == "OK") {

    $Authority = (isset($_POST["Authority"]) && $_POST["Authority"] != "") ? $_POST["Authority"] : "";
    $InvoiceID = (isset($_POST["InvoiceID"]) && $_POST["InvoiceID"] != "") ? $_POST["InvoiceID"] : "";

    $data = [
        "MerchantID" => "xxxx-xxx-xxxxxxxxxxxx-xxxxxxxxxx",
        "Amount" => 500000,
        "Authority" => $Authority
    ];

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, "https://api.novinopay.com/Payment/rest/v1/Verification");
    curl_setopt($curl, CURLOPT_HTTPHEADER, ["Content-Type" => "application/json"]);
    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
    curl_setopt($curl, CURLOPT_TIMEOUT, 50);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $curl_exec = curl_exec($curl);
    curl_close($curl);

    $result = json_decode($curl_exec);

    if (isset($result->Status) && $result->Status == 100) {
        echo "Invoice Succecfully Paid | Price: {$result->Amount} Toman | RefID: {$result->RefID}";
    } else {
        echo isset($result->Status) ? "Error Code: {$result->Status} | {$result->Message}" : "Error Connecting to novinopay.com";
    }

}


?>

جدول خطا
کد شرح
100 عملیات موفقیت آمیز
101 عمليات پرداخت موفق بوده و قبلا تاییدیه تراكنش انجام شده است
-1 صرفا درخواست با متد POST قابل پذیرش است
-2 مقداری برای MerchantID ارسال نشده است
-3 مقداری برای Amount ارسال نشده است
-4 مقداری برای CallbackURL ارسال نشده است
-5 مبلغ صحیح نمیباشد
-6 MerchantID وارد شده در سیستم یافت نشد
-7 MerchantID وارد شده فعال نیست
-8 اکانت شما تجاری نیست, لذا امکان استفاده از وبسرویس را ندارید
-9 IP معتبر نیست
-10 آدرس بازگشتی با آدرس درگاه پرداخت ثبت شده همخوانی ندارد
-11 خطای در وب سرویس - ایجاد تراکنش با خطا مواجه شد
-12 مقدار Authority ارسالی معتبر نیست - تراکنش یافت نشد
-13 مقداری برای Authority ارسال نشده است
-14 اطلاعات تراکنش یافت نشد, مقدار Authority را برسی کرده و صحیح بودن آن اطمانان حاصل کنید
-15 تراکنش در انتظار پرداخت میباشد
-16 مبلغ ارسال شده با مبلغ تراکنش یکسان نیست, مقدار Amount را برسی کرده و نسبت به صحت آن اطمینان حاصل کنید
-17 دسترسی شما به این تراکنش رد شد, Authority این تراکنش برای MerchantID شما ثبت نشده است
-18 پرداخت تراکنش با موفقیت انجام شده است, اما در بروزرسانی کیف پول پذیرنده مشکلی پیش آمده است
-19 وضعیت تراکنش نامشخص است
-20 تراکنش ناموفق بوده و امکان عملیات تاییدیه تراکنش وجود ندارد
-21 تراکنش منقضی شده است
-22 تراکنش به حساب کاربرمرجوع شده است
-23 مدت زمان عملیات تاییدیه تراکنش منقضی شده و مبلغ به حساب کاربر برگشت خواهد خورد
-24 شماره کارت ارسالی جهت پرداخت معتبر نمیباشد
-25 مجموع مبلغ تراکنش و کارمزد نباید بیش از 50.000.000 تومان باشد

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