راهنمای وب سرویس (REST)

همانطور که میدونید API کوتاه شده ی عبارت Application Programming Interface هستش که به برنامه نویسان این اجاره رو میده تا اطلاعت رو بین پلتفرم های مختلف از طریق درخواست های HTTP یا HTTPS رد و بدل کنند.

REST هم یه روش بسیار ساده برای استفاده از API و البته محبوبترین و پر کاربردترین هم هست.

Pay.ir این امکان رو به برنامه نویسان میده تا با استفاده از REST وب سایت مورد نظرشون رو به درگاه پرداخت Pay.ir متصل کنند.

نکته : تمامی داده های برگشتی از Pay.ir به صورت json می باشد


نیازمندی ها

نیازمندی سایت شما برای اتصال به سیستم پرداخت Pay.ir فقط فعال بودن تابع curl بوده که در اکثر سرور ها این تابع فعال می باشد. برای مطمئن شدن از فعال بودن این تابع با مدیر سرور خود تماس بگیرید.


مرحله اول ( ارسال داده ها )

اولین مرحله برای اتصال به درگاه پرداخت Pay.ir ارسال داده ها از طریق متد زیر هستش.

ساختار URL :

https://pay.ir/payment/send

داده های ارسالی :

نام فیلد نوع فیلد توضیحات
api string API Key دریافتی شما از Pay.ir
amount integer مبلغ تراکنش به صورت ریالی و بزرگتر یا مساوی 1000
redirect string آدرس بازگشتی به صورت urlencode ، که باید با آدرس درگاه پرداخت تایید شده در Pay.ir بر روی یک دامنه باشد
factorNumber string شماره فاکتور شما (اختیاری)

داده های دریافتی :

در صورتی که اطلاعات ارسالی صحیح باشد :

{
    "status" : 1,
    "transId": شماره تراکنش
}

در صورت بروز خطا :

{
    "status"       : 0,
    "errorCode"    : کد خطا,
    "errorMessage" : متن پیام خطا
}

جدول خطاها به شرح زیر می باشد :

کد خطا متن خطا
-1 ارسال api الزامی می باشد
-2 ارسال amount ( مبلغ تراکنش ) الزامی می باشد
-3 amount ( مبلغ تراکنش )باید به صورت عددی باشد
-4 amount نباید کمتر از 1000 باشد
-5 ارسال redirect الزامی می باشد
-6 درگاه پرداختی با api ارسالی یافت نشد و یا غیر فعال می باشد
-7 فروشنده غیر فعال می باشد
-8 آدرس بازگشتی با آدرس درگاه پرداخت ثبت شده همخوانی ندارد
failed تراکنش با خطا مواجه شد

مرحله دوم ( انتقال به صفحه پرداخت )

در صورتی که در مرحله قبل (ارسال داده ها) ، اطلاعات ارسالی صحیح باشد و دو مقدار status و transId رو به عنوان پاسخ از Pay.ir دریافت کردید باید کاربر رو به آدرس زیر انتقال دهید. نکته : به جای {transId} مقدار transId دریافتی رو قرار بدین

https://pay.ir/payment/gateway/{transId}

مرحله سوم ( بازگشت به سایت پذیرنده پس از پرداخت )

پس از انجام پرداخت Pay.ir مقادیر زیر رو به صورت POST به آدرس بازگشتی که در مرحله اول وارد کردید ارسال میکنه

نام فیلد نوع فیلد توضیحات
status integer وضعیت تراکنش : مقدار 1 موفق و مقدار 0 ناموفق
transId integer شماره تراکنش
factorNumber string شماره فاکتور ارسالی توسط شما در مرحله اول
cardNumber string شماره کارتی که تراکنش با آن انجام شده است
message string متن پیام

مرحله چهارم ( وریفای یا تایید تراکنش )

در صورتی که در مرحله قبل مقدار فیلد status برابر یا عدد صحیح 1 باشه باید برای تایید تراکنش (وریفای) و دریافت مبلغ تراکنش از طریق متد زیر اقدام کنید.

توجه ! درصورت موفقیت آمیز بودن تراکنش، با هربار فراخوانی متد وریفای، سرویس Pay تایید تراکنش را اعلام می کند. پذیرنده می بایست با استفاده از شماره تراکنش Pay.ir ( همان transId ) از unique بودن آن در دیتابیس خود اطمینان حاصل نماید

ساختار URL :

https://pay.ir/payment/verify

داده های ارسالی :

نام فیلد نوع فیلد توضیحات
api string API Key دریافتی شما از Pay.ir
transId integer transId دریافتی از مرحله سوم

داده های دریافتی :

در صورتی که اطلاعات ارسالی صحیح باشد و تراکنش تایید (وریفای) شود :

{
    "status" : 1,
    "amount": مبلغ تراکنش
}

در صورت بروز خطا :

{
    "status"       : 0,
    "errorCode"    : کد خطا,
    "errorMessage" : متن پیام خطا
}

جدول خطاها به شرح زیر می باشد :

کد خطا متن خطا
-1 ارسال api الزامی می باشد
-2 ارسال transId الزامی می باشد
-3 درگاه پرداختی با api ارسالی یافت نشد و یا غیر فعال می باشد
-4 فروشنده غیر فعال می باشد
-5 تراکنش با خطا مواجه شده است

API آزمایشی


برنامه نویسان میتونند برای تست درگاه در حین کدنویسی به صورت زیر عمل کنند

برای استفاده فقط مقدار متغیر api رو برابر با test قرار دهید


نمونه کد PHP


function send($api, $amount, $redirect, $factorNumber=null) {
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'https://pay.ir/payment/send');
	curl_setopt($ch, CURLOPT_POSTFIELDS,"api=$api&amount=$amount&redirect=$redirect&factorNumber=$factorNumber");
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
	$res = curl_exec($ch);
	curl_close($ch);
	return $res;
}

function verify($api, $transId) {
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, 'https://pay.ir/payment/verify');
	curl_setopt($ch, CURLOPT_POSTFIELDS, "api=$api&transId=$transId");
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
	$res = curl_exec($ch);
	curl_close($ch);
	return $res;
}