به منظور استفاده و اتصال به وب سرویس نیاز است روی هاست شما SOAP فعال باشد, البته در صورتی که روی هاست شما SOAP فعال نباشد, میتوانید کتابخانه NuSOAP را در اسکریپت / برنامه تان include یا فراخوانی کنید, همچنین میتوانید به جای استفاده از SOAP یا فراخوانی کتابخانه NuSOAP از وب سرویس CURL / Restful استفاده کنید.
وب سرویس
در این نوع وب سرویس کلیه درخواست ها باید به آدرس
http://www.negarmarket.ir/webservice/soap/?wsdl ارسال شوند, لذا در کد نویسی دقت داشته باشید آدرس وب سرویس SOAP / NuSOAP به شکل زیر خواهد بود :
http://www.negarmarket.ir/webservice/soap/?wsdl
واژگان
1.
پذيرنده : شخص ، سازمان و يا شركتي كه محصول يا سرويسي را از طريق اينترنت ارائه مي كند.
2.
خريدار : شخص دارنده كارتهاي شتاب يا حساب گیت پال - درگاه پرداخت واسط الکترونیک كه قصد خريد يا دريافت سرويس از جانب پذيرنده اي را دارد.
3.
بانك عامل : بانكي است كه خريدار در گیت پال - درگاه پرداخت واسط الکترونیک انتخاب نموده و اطلاعات كارت شتاب خود را در آن سايت وارد مينمايد.
4.
تراكنش : يك عمليات مالي، كه در اين نوشته مصداق آن يك خريد مي باشد.
5.
رمزينه : نوعي نمايش تصويري اطلاعات بر روي سطوح است كه اطلاعات آن را ميتوان توسط ماشين بازخواني كر
مکانیزم کلی درگاه پرداخت گیت پال - درگاه پرداخت واسط الکترونیک بر دو اصل سادگی و امنیت پایه ریزي شده است. بطوریکه یک برنامه نویس با خواندن نکات ، درك مفاهیم و دیدن sample کدهاي موجود در این بخش به راحتی و در کمتر از 10 دقیقه می تواند سایت شما را به سیستم پرداخت گیت پال - درگاه پرداخت واسط الکترونیک متصل نماید
امنیت :
در عین سادگی گیت پال - درگاه پرداخت واسط الکترونیک از مکانیزم هاي امنیتی استفاده می کند تا تراکنش ها در امنیت کامل انجام شوند.
نیازمندی ها :
به منظور استفاده از این نوع وب سرویس لازم است که روی هاست شما SOAP فعال باشد و یا کتابخانه NuSOAP را در درون اسکریپت یا برنامه خود include کنید.
داده های ارسالی :
بطور کلی سایت مبدا براي انجام تراکنش باید موارد زیر را به آدرس
http://www.negarmarket.ir/webservice/soap/?wsdl از طربق فراخوانی متد PaymentRequest ارسال کند
PaymentRequest(
'MerchantID' => $MerchantID,
'Amount' => $Amount,
'Description' => $Description,
'CallbackURL' => $CallbackURL,
'InvoiceNumber' => $InvoiceNumber,
'CardNumber' => $CardNumber
);
پارمترهاي ورودي متد PaymentRequest به شرح زير مي باشند :
پارامترهای ارسالی |
مثال |
توضیح |
MerchantID |
xxxxxxxxxxxxxxxx |
مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد |
Amount |
100 |
مبلغی که در تراکنش ارسال و قابل پرداخت میباشد, واحد مبلغ ارسالی تومان و حداقل مبلغ قابل پرداخت 100 تومان میباشد |
Description |
تراکنش شماره 15 |
متني كه توسط پذيرنده تعيين ميشود كه نشان دهنده خلاصه محصول يا سرويسي است كه پذيرنده قصد فروش آن را دارد |
CallbackURL |
http://example.com/verify.php |
آدرس بازگشتی که بعد از انجام عملیات تراکنش، گیت پال - درگاه پرداخت واسط الکترونیک اطلاعات را به آنجا ارسال خواهد کرد |
InvoiceNumber |
15 |
شماره تراکنش, این شماره پس از پرداخت برای سایت فروشنده ارسال خواهد شد |
CardNumber |
6037991100000000 |
شماره کارت پرداخت کننده ( این مورد میتواند خالی باشد ) |
مقاديريكه توسط متد PaymentRequest برگشت داده ميشود به شرح زير ميباشد :
پارامترهای برگشتی |
مثال |
توضیح |
Status |
100 |
وضعيت درخواست كه در صورت موفقيت آميز بودن برابر 100 در غير اين صورت عددي منفي ميباشد |
Authority |
1000010 |
شناسه مرجع درخواست، درصورت موفق بودن داراي یک عدد صحیح می باشد |
در صورت صحت داده ها گیت پال - درگاه پرداخت واسط الکترونیک یک داده از نوع صحیح و بزرگتر از 0 ( که Authority نام دارد ) و یک داده با نام Status برابر 100 بر می گرداند و سایت پذیرنده پس از دریافت این داده ها، مشتري را به سایت گیت پال - درگاه پرداخت واسط الکترونیک هدایت می نماید, توجه داشته باشید که در داده های برگشتی در صورتی که مقدار Status برابر با 100 نباشد, برابر با یک عدد منفی خواهد بود که شرح خطاهای هر عدد منفی را در تب
کدهای برگشتی / خطاها / توضیحات مشاهده کنید.
بطور مثال در صورتی که مقدار Authority بازگشتی برابر با 1000010 باشد بمنظور اتصال به درگاه بانکی و انجام عملیات پرداخت کاربر باید به آدرس زیر هدایت شود :
http://www.negarmarket.ir/startPay/1000010
نمونه کد PHP ایجاد شناسه ی پرداخت ( Authority ) و ارجاع کاربر به درگاه پرداخت :
<?php
$MerchantID = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$Amount = 1000;
$Description = 'توضیحات تراکنش تستی';
$CallbackURL = 'http://example.com/verify.php';
$InvoiceNumber = 15;
$CardNumber = '';
$client = new SoapClient('http://www.negarmarket.ir/webservice/soap/?wsdl', ['encoding' => 'UTF-8']);
$result = $client->PaymentRequest([
'MerchantID' => $MerchantID,
'Amount' => $Amount,
'Description' => $Description,
'CallbackURL' => $CallbackURL,
'InvoiceNumber' => $InvoiceNumber,
'CardNumber' => $CardNumber,
]);
//Redirect to URL You can do it also by creating a form
if (isset($result->Status) && $result->Status == 100)
{
header('Location: http://www.negarmarket.ir/startPay/'. $result->Authority);
} else {
echo (isset($result->Status) && $result->Status != "") ? $result->Status : "-13";
}
?>
<?php
require_once 'lib/nusoap.php';
$MerchantID = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$Amount = 1000;
$Description = 'توضیحات تراکنش تستی';
$CallbackURL = 'http://example.com/verify.php';
$InvoiceNumber = 15;
$CardNumber = '';
$client = new nusoap_client('http://www.negarmarket.ir/webservice/soap/?wsdl', 'wsdl');
$client->soap_defencoding = 'UTF-8';
$result = $client->call('PaymentRequest', [
[
'MerchantID' => $MerchantID,
'Amount' => $Amount,
'Description' => $Description,
'CallbackURL' => $CallbackURL,
'InvoiceNumber' => $InvoiceNumber,
'CardNumber' => $CardNumber,
],
]);
//Redirect to URL You can do it also by creating a form
if (isset($result['Status']) && $result['Status'] == 100)
{
header('Location: http://www.negarmarket.ir/startPay/'. $result['Authority']);
} else {
echo (isset($result['Status']) && $result['Status'] != "") ? $result['Status'] : '-13';
}
?>
بعد از پايان عمليات درسمت گیت پال - درگاه پرداخت واسط الکترونیک گیت پال - درگاه پرداخت واسط الکترونیک وظيفه دارد كاربر را به سايت پذيرنده كه از طريق CallbackURL مشخص شده است بازگرداند.
در صفحه CallbackURL پذيرنده وظيفه دارد درخواست معادل با Authority كه از طـرف گیت پال - درگاه پرداخت واسط الکترونیک و بـه صـورت QueryString بـر روي CallbackURL ارسال شده يافته و وضعيت تراكنش ( Status ) كه از همين طريق ارسال شده است را با متـد PaymentVerification چـك نمايد در صورت موفق بودن، پرداخت را ثبت و شماره تراكنش را به كاربر خريدار نمايش دهد ؛ در غير اينصورت پذيرنده موظف اسـت كـه بـا توجه به كد خطايي كه توسط متد PaymentVerification دريافت ميكند كاربر را از خطاي رخ داده مطلع سازد.
PaymentVerification(
'MerchantID' => $MerchantID,
'Authority' => $Authority,
'Amount' => $Amount
);
نکته توجه داشته باشيد كه به جز Status كه در متد PaymentVerification قرار دارد يك Status نيز به صورت QueryString به
سايت پذيرنده ارسال ميگردد كه دو مقدار ثابت دارد “OK “و“NOK “؛ در صورتي كه اين مقدار برابر “NOK “بود به اين معنا بوده كه
تراكنش نا موفق بوده و يا توسط كاربر لغو شده است؛ پس در صورتي متد PaymentVerification استفاده شود كه با QueryString
مقدار Status برابر با “OK “باشد.
مقاديريكه توسط متد PaymentVerification برگشت داده ميشود به شرح زير ميباشد :
پارامترهای برگشتی |
مثال |
توضیح |
Status |
100 |
وضعيت درخواست كه در صورت موفقيت آميز بودن برابر 100 در غير اين صورت عددي منفي ميباشد |
RefID |
1000010 |
در صورتي كه پرداخت موفق باشد؛ شماره تراكنش پرداخت انجام شده را بر ميگرداند. |
Amount |
1000 |
مبلغ پرداخت شده ( مبلغ به تومان می باشد ) |
MaskCardNumber |
123456****894564 |
شماره کارت Mask شده خریدار ( شماره کارتی که پرداخت وجه توسط آن انجام شده است ) |
در صورتی که مقدار بازگشتی Status برابر با 100 باشد تراکنش بدرستی انجام شده است در غیر اینصورت مقدار بازگشتی برابر با یک عدد منفی خواهد بود که شرح خطاهای مرتبط با هر عدد منفی بازگشتی را میتوانید در تب
کدهای برگشتی / خطاها / توضیحات مشاهده کنید
نمونه کد PHP تصدیق اصالت پس از پرداخت ( عملیات Verify کردن تراکنش ) :
<?php
$MerchantID = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$Amount = 1000;
$Authority = (isset($_GET['Authority']) && $_GET['Authority'] != "") ? $_GET['Authority'] : "";
if (isset($_GET['Status']) && $_GET['Status'] == 'OK')
{
$client = new SoapClient('http://www.negarmarket.ir/webservice/soap/?wsdl', ['encoding' => 'UTF-8']);
$result = $client->PaymentVerification([
'MerchantID' => $MerchantID,
'Authority' => $Authority,
'Amount' => $Amount,
]);
if (isset($result->Status) && $result->Status == 100)
{
echo 'Transation success. Amount : '. $result->Amount .' Toman AND RefID : '. $result->RefID;
} else {
echo (isset($result->Status) && $result->Status != "") ? $result->Status : "-13";
}
} else {
echo 'Transaction canceled by user';
}
?>
<?php
require_once 'lib/nusoap.php';
$MerchantID = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$Amount = 1000;
$Authority = (isset($_GET['Authority']) && $_GET['Authority'] != "") ? $_GET['Authority'] : "";
if (isset($_GET['Status']) && $_GET['Status'] == 'OK')
{
$client = new nusoap_client('http://www.negarmarket.ir/webservice/soap/?wsdl', 'wsdl');
$client->soap_defencoding = 'UTF-8';
$result = $client->call('PaymentVerification', [
[
'MerchantID' => $MerchantID,
'Authority' => $Authority,
'Amount' => $Amount,
],
]);
if (isset($result['Status']) && $result['Status'] == 100)
{
echo 'Transation success. Amount : '. $result['Amount'] .' Toman AND RefID : '. $result['RefID'];
} else {
echo (isset($result['Status']) && $result['Status'] != "") ? $result['Status'] : '-13';
}
} else {
echo 'Transaction canceled by user';
}
?>