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

---

کلیه درخواست های ایجاد و شروع تراکنش باید به آدرس https://gooyapay.ir/webservice/rest/PaymentRequest و کلیه درخواست های بررسی وضعیت و Verify کردن تراکنش به آدرس https://gooyapay.ir/webservice/rest/PaymentVerification ارسال شوند, لذا در کد نویسی دقت داشته باشید آدرس وب سرویس RestFul به شکل زیر خواهد بود :

https://gooyapay.ir/webservice/rest/PaymentRequest

https://gooyapay.ir/webservice/rest/PaymentVerification

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

---

سایت مبدا براي ایجاد و شروع تراکنش باید با توجه به جدول زیر, اطلاعات و دیتاهای مورد نیاز را به آدرس https://gooyapay.ir/webservice/rest/PaymentRequest و به شیوه POST ارسال نماید

پارامتر	نوع	وضعیت	شرح
MerchantID	string	اجباری	مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Amount	integer	اجباری	مبلغی که در تراکنش ارسال و قابل پرداخت میباشد. واحد مبلغ ارسالی تومان می باشد حداقل مبلغ قابل پرداخت 1,000 تومان و حداکثر 200.000.000 تومان میباشد
InvoiceID	string	اختیاری	شناسه, این شناسه پس از پرداخت برای سایت فروشنده ارسال خواهد شد
Description	string	اختیاری	توضيحات مربوط تراكنش
Email	string	اختیاری	آدرس ایمیل خریدار
Mobile	string	اختیاری	شماره تماس خریدار
CallbackURL	string	اجباری	صفحه بازگشت مشتري، پس از انجام عمل پرداخت
AllowCard	string	اختیاری	شماره کارت پرداخت کننده به منظور محدود سازی امکان پرداخت تنها توسط یک کارت, شماره 16 رقمی کارت را بدون خط تیره و بدون فاصله وارد کنید.

لیست داده هاي برگشتی در پاسخ به فرايند خريد ( Request )

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

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

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

بطور مثال در صورتی که مقدار Status برابر با 100 و مقدار Authority دارای یک کد 32 کاراکتری ( به عنوان مثال : F5122EEC8CA035EC3A3C7318B333BB28 ) باشد بمنظور اتصال به درگاه بانکی و انجام عملیات پرداخت کاربر باید به آدرس زیر هدایت شود :

https://gooyapay.ir/startPay/F5122EEC8CA035EC3A3C7318B333BB28

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

<?php
$MerchantID 	= 'XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXXXXXXX';
$Amount 	= 1000;
$InvoiceID 	= 10;
$Description 	= 'Payment ID 10';
$FullName 	= 'buyer name';
$Email 		= 'buyer@example.com';
$Mobile 	= '09123456789';
$CallbackURL 	= 'http://example.com/verify.php';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gooyapay.ir/webservice/rest/PaymentRequest');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array(
		'MerchantID' 	=> $MerchantID,
		'Amount' 	=> $Amount,
		'InvoiceID' 	=> $InvoiceID,
		'Description' 	=> $Description,
		'FullName' 	=> $FullName,
		'Email' 	=> $Email,
		'Mobile' 	=> $Mobile,
		'CallbackURL' 	=> $CallbackURL
	)));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
		'Content-Type: application/json',
		'Accept: application/json'
	));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($ch);
$error = curl_error($ch);
curl_close($ch);

$result = json_decode($response);

if (isset($result->Status) && $result->Status == 100)
{
	header('Location: ' . $result->PaymentUrl);
}
elseif (isset($result->Message) && $result->Message != '')
{
	echo 'Error : ' . $result->Message;
}
elseif ($error)
{
	echo 'Connecting Error : ' . $error;
}
else
{
	echo 'UnExpected Error in connecting to web service';
}

?>

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

---

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

براي Verify کردن تراکنش باید اطلاعات و دیتاهای مورد نیاز را طبق جدول زیر به آدرس https://gooyapay.ir/webservice/rest/PaymentVerification از طریق متد POST ارسال کند

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

لیست داده هاي برگشتی در پاسخ به فرايند استعلام تراکنش ( Verify )

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

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

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

<?php
$MerchantID 	= 'XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXXXXXXX';
$Amount 	= 1000;

if (isset($_POST['PaymentStatus']) && $_POST['PaymentStatus'] == 'OK')
{
	$Authority 	= (isset($_POST['Authority']) && $_POST['Authority'] != '') ? $_POST['Authority'] : '';
	$InvoiceID 	= (isset($_POST['InvoiceID']) && $_POST['InvoiceID'] != '') ? $_POST['InvoiceID'] : '';

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'https://gooyapay.ir/webservice/rest/PaymentVerification');
	curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array(
			'MerchantID' 	=> $MerchantID,
			'Amount' 	=> $Amount,
			'Authority' 	=> $Authority
		)));
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(
			'Content-Type: application/json',
			'Accept: application/json'
		));
	curl_setopt($ch, CURLOPT_TIMEOUT, 30);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
	$response = curl_exec($ch);
	curl_close($ch);

	$result = json_decode($response);

	if (isset($result->Status) && $result->Status == 100)
	{
		echo 'Transation success. Amount : '. $result->Amount .' Toman AND RefID : '. $result->RefID;
	}
	elseif (isset($result->Message) && $result->Message != '')
	{
		echo 'Error : ' . $result->Message;
	}
	elseif ($error)
	{
		echo 'Connecting Error : ' . $error;
	}
	else
	{
		echo 'UnExpected Error in connecting to web service';
	}
}
else
{
	echo 'Transaction Cancelled By User';
}

?>