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

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

Payment Request :

http://rahapal.com/webservice/rest/PaymentRequest

Payment Verify :

http://rahapal.com/webservice/rest/PaymentVerification

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

سایت مبدا برای ایجاد و شروع تراکنش باید با توجه به جدول زیر, اطلاعات و دیتاهای مورد نیاز را به آدرس http://rahapal.com/webservice/rest/PaymentRequest و به شیوه POST ارسال نماید.

پارامتر نوع وضعیت شرح
MerchantID string اجباری مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Amount integer اجباری مبلغی که در تراکنش ارسال و قابل پرداخت میباشد, واحد مبلغ ارسالی تومان و حداقل مبلغ قابل پرداخت ۱۰۰ تومان میباشد
InvoiceID string اختیاری شناسه, این شناسه پس از پرداخت برای سایت فروشنده ارسال خواهد شد
Description string اختیاری توضیحات مربوط تراکنش
Email string اختیاری آدرس ایمیل خریدار
Mobile string اختیاری شماره تماس خریدار
CallbackURL string اجباری صفحه بازگشت مشتری، پس از انجام عمل پرداخت

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

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

در صورت صحت داده ها رهاپال یک داده از نوع string به طول ۳۲ کاراکتر ( که Authority نام دارد ) و یک داده با نام Status برابر ۱۰۰ بر می گرداند و سایت پذیرنده پس از دریافت این داده ها، مشتری را به سایت رهاپال هدایت می نماید, توجه داشته باشید که در داده های برگشتی در صورتی که مقدار Status برابر با ۱۰۰ نباشد, برابر با یک عدد منفی خواهد بود که شرح خطاهای هر عدد منفی را در تب کدهای برگشتی / خطاها مشاهده کنید.

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

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

http://rahapal.com/startPay/F5122EEC8CA035EC3A3C7318B333BB28

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

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

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://rahapal.com/webservice/rest/PaymentRequest');
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type' => 'application/json'));
curl_setopt($curl, CURLOPT_POSTFIELDS, "MerchantID={$MerchantID}&Amount={$Amount}&InvoiceID={$InvoiceID}&Description={$Description}&Email={$Email}&Mobile={$Mobile}&CallbackURL=". urlencode($CallbackURL));
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
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) && $result->Status != "") ? $result->Status : "Error connecting to web service";
}
?>

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

در صفحه CallbackURL پذیرنده وظیفه دارد درخواست معادل با Authority و PaymentStatus که از طـرف رهاپال و بـه صـورت POST به آدرس CallbackURL ارسال شده است را دریافت نموده و در صورتی که مقدار PaymentStatus دریافت شده برابر با ” OK ” بود, داده‌های جدول زیر را از طریق متـد POST به آدرس http://rahapal.com/webservice/rest/PaymentVerification ارسال نموده و پاسخ دریافتی را چـک نماید و در صورت موفق بودن، پرداخت را ثبت و شماره تراکنش را به کاربر خریدار نمایش دهد ؛ در غیر اینصورت پذیرنده موظف اسـت کـه بـا توجه به کد خطایی که دریافت میکند کاربر را از خطای رخ داده مطلع سازد. همچنین توجه داشته باشید در صورتی PaymentStatus برابر با ” NOK ” باشد, تراکنش ناموفق بوده و نیازی به ارسال درخواست PaymentVerification نیست.
 
برای Verify کردن تراکنش باید اطلاعات و دیتاهای مورد نیاز را طبق جدول زیر به آدرس http://rahapal.com/webservice/rest/PaymentVerification از طریق متد POST ارسال کند
پارامتر نوع وضعیت شرح
MerchantID string اجباری مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Authority string اجباری کد یکتای شناسه مرجع درخواست
Amount integer اجباری مبلغ فاکتور به تومان - مبلغ ارسالی باید با مبلغ اولیه فاکتور در زمان ایجاد تراکنش یکسان باشد

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

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

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

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

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

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

	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, 'http://rahapal.com/webservice/rest/PaymentVerification');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type' => 'application/json'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, "MerchantID={$MerchantID}&Amount={$Amount}&Authority={$Authority}");
	curl_setopt($curl, CURLOPT_TIMEOUT, 30);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
	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 'Transation success. Amount : '. $result->Amount .' Toman AND RefID : '. $result->RefID;
	} else {
		echo (isset($result->Status) && $result->Status != "") ? $result->Status : "Error connecting to web service";
	}
} else {
	echo 'Transaction Canceled By User';
}
?>
پارامتر نوع وضعیت شرح
MerchantID string اجباری مرچنت آیدی در بخش " درگاهای من " در پنل کاربری شما در قابل مشاهده میباشد
Amount integer اجباری مبلغی که در تراکنش ارسال و قابل پرداخت میباشد, واحد مبلغ ارسالی تومان و حداقل مبلغ قابل پرداخت ۱۰۰ تومان میباشد
InvoiceID string اختیاری شناسه, این شناسه پس از پرداخت برای سایت فروشنده ارسال خواهد شد
Description string اختیاری توضیحات مربوط تراکنش
Email string اختیاری آدرس ایمیل خریدار
Mobile string اختیاری شماره تماس خریدار
CallbackURL string اجباری صفحه بازگشت مشتری، پس از انجام عمل پرداخت