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


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

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



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


سایت مبدأ برای ایجاد و شروع تراکنش باید با توجه به جدول زیر، اطلاعات و فیلدهای مورد نیاز را به آدرس https://panel.darickpay.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://panel.darickpay.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://panel.darickpay.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://panel.darickpay.com/webservice/rest/PaymentVerification ارسال نموده و پاسخ دریافتی را چـك نماید و در صورت موفق بودن، پرداخت را ثبت و شماره تراكنش را به كاربر خریدار نمایش دهد؛ در غیر اینصورت پذیرنده موظف اسـت كـه بـا توجه به كد خطایی كه دریافت میكند كاربر را از خطای رخ داده مطلع سازد. همچنین توجه داشته باشید در صورتی که  PaymentStatus برابر با " NOK " باشد، تراکنش ناموفق بوده و نیازی به ارسال درخواست PaymentVerification نیست.

برای Verify کردن تراکنش باید اطلاعات و فیلدهای مورد نیاز را طبق جدول زیر به آدرس https://panel.darickpay.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://panel.darickpay.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';
}
?>