مستندات فنی

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

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

Payment Request:
https://lotuspal.com/webservice/rest/PaymentRequest
Payment Verify:
https://lotuspal.com/webservice/rest/PaymentVerification


فرایند درخواست (Request)

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

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

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

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

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

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

https://lotuspal.com/startPay/F5122EEC8CA035EC3A3C7318B333BB28

نمونه کد PHP ایجاد شناسه پرداخت (Authority) و ارجاع کاربر به درگاه پرداخت
<?php
$MerchantID 	= "XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXXXXXXX";
$Amount 	= 1000;
$InvoiceID 	= 10;
$Description 	= "Payment ID 10";
$Email 		= "buyer@example.com";
$Mobile 	= "09123456789";
$CallbackURL 	= "http://example.com/verify.php";

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://lotuspal.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 به آدرس:

https://lotuspal.com/webservice/rest/PaymentVerification

ارسال نموده و پاسخ دریافتی را بررسی نمايد و در صورت موفق بودن ، پرداخت را ثبت و شماره تراكنش را به كاربر خريدار نمايش دهد؛ در غير اينصورت پذيرنده موظف اسـت كـه بـا توجه به كد خطايی كه دريافت می‌كند كاربر را از خطای رخ داده مطلع سازد. همچنین توجه داشته باشید در صورتی PaymentStatus برابر با "NOK" باشد ، تراکنش ناموفق بوده و نیازی به ارسال درخواست PaymentVerification نیست.

به منظور Verify تراکنش باید اطلاعات و دیتاهای مورد‌نیاز را طبق جدول زیر به آدرس https://lotuspal.com/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'] : "";

	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, 'https://lotuspal.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';
}
?>