اتصال از طریق وب‌سرویس RESTful سومین روشی است که در پایرت‌ پی پیاده سازی شد، در این راهنما قصد داریم تا به زبان ساده روش‌های اتصال با آن را توضیح دهیم، یادآور می‌شویم در این راهنما از زبان برنامه نویسی PHP استفاده خواهیم کرد

قدم اول : معرفی متغیر‌هایی که باید از سمت پذیرنده ارسال شود

* merchantId : کد پذیرنده که به صورت یکتا توسط پایرت پی ایجاد شده و در قسمت درگاه‌های پرداخت در پایرت پی در دسترس می باشد، این کد برای تمامی سایت‌های پذیرنده یکی است

* amount : مبلغ کالا و خدماتی است که پذیرنده ارائه می دهد

* callbackURL : آدرسی است که پایرت پی کاربر پذیرنده را بعد از پرداخت موفق یا ناموفق به آن هدایت می کند

* pspId : کد بانکی است که پذیرنده تمایل دارد تا کاربرش پرداخت‌ها را از طریق آن انجام دهد، در صورتی که این مقدار خالی ارسال شود کاربر به بانک پیش‌فرض منتقل خواهد شد، کد بانک می توانید یکی از اعداد زیر باشد

0 - خودکار (فقط درگاه‌های ریالی)

1 - بانک ملت

2 - بانک پارسیان

3- بانک پاسارگاد

4 - آسان پرداخت پرشین

5- بانک ملی

6 - بانک سامان

7 - بیت کوین

8 - پرفکت مانی

9 - پی پال

10 - وب مانی

* description : توضیحاتی در مورد کالا و خدمات ارائه شده توسط پذیرنده

currency : واحد پولی که می تواند یکی از دو مورد IRR برای پرداخت‌های ریالی و USD برای پرداخت‌های دلاری باشد

payerName : نام پرداخت کننده

payerSurname : نام خانوادگی پرداخت کننده

payerEmail :‌ ایمیل پرداخت کننده

payerMobile : شماره موبایل پرداخت کننده

payerPhone : شماره تلفن پرداخت کننده

terminalId : در صورتی که سایت پذیرنده دارای کد ترمینال اختصاصی باشد این مقدار باید توسط وی ارسال شود

توجه : ارسال متغیر‌هایی که با ستاره مشخص شده است اجباری است

قدم دوم : فراخوانی وب‌سرویس برای درخواست ایجاد تراکنش پرداخت

<?php

$merchantId = 'xxxxxxxxxxxxx'; 
$amount = 1000; 
$callbackURL = 'http(s)://domain.ltd/getVerify.php';
$pspId = 1;
$description = 'Payment Description'; 
$currency = 'IRR';
$payerName = 'کوروش';
$payerSurname = 'کبیر';
$payerEmail = 'korosh@gmail.com';
$payerMobile = '09123456789';
$payerPhone = '021123456789';
$terminalId = '';

$URL = "https://piratepay.ir/api/v2/sendPayment?merchantId=$merchantId&amount=$amount&callbackURL=$callbackURL&pspId=$pspId&description=$description&currency=$currency&payerName=$payerName&payerSurname=$payerSurname&payerEmail=$payerEmail&payerMobile=$payerMobile&payerPhone=$payerPhone&terminalId=$terminalId";
$response = file_get_contents($URL);
$result = json_decode($response);
if($result->status){
	$authority = $result->authority;
	header("location: $result->paymentURL");
	exit();
}
else
	echo $result->message;

با فراخوانی تابع sendPayment با متغیر‌های موصوف در صورتی که حساب کاربری شما در پایرت پی فعال بوده و سایت شما دارای درگاه فعال باشد چهار متغیر در قالب یک شی دریافت می کنید که به صورت زیر است

status : وضعیت درخواست که می تواند یکی از مقادیر true یا false باشد

message : پیام سیستم و خطاها از طریق این متغیر قابل دسترسی است

authority : مقدار یکتایی که توسط پایرت پی برای تراکنش درخواستی ایجاد می شود

paymentURL : آدرسی است که کاربر برای پرداخت باید به آن منتقل شود

توجه : در صورتی که مشکلی در فرآیند درخواست رخ دهد تنها دو متغیر status و message را دریافت خواهید کرد.

حال در صورتی که مقدار status برابر با true باشد باید مقدار یکتای authority را نگهداری و کاربر را به paymentURL ریدایرکت نمایید در غیر این صورت message را نشان دهید.

قدم سوم : فراخوانی وب‌سرویس برای تایید تراکنش پرداخت

برای فراخوانی تابع getVerify که عمل تایید تراکنش را انجام می دهد دو متغیر زیر باید ارسال شود

* merchantId : کد پذیرنده

* authority : کد یکتای تراکنش که توسط پایرت پی ارسال شده بود

<?php

$merchantId = 'xxxxxxxxxxxxx';
$authority = trim($_GET['authority']);

$URL = "https://piratepay.ir/api/v2/getVerify?merchantId=$merchantId&authority=$authority";
$response = file_get_contents($URL);
$result = json_decode($response);
if($result->status && $result->message == 'OK')
	echo 'Payment OK';
elseif($result->status && $result->message == 'COMMIT')
	echo 'Payment OK & COMMIT';
else
	echo $result->message;

با فراخوانی تابع getVerify با متغیر‌های ارسالی سه متغیر در قالب یک شی دریافت می کنید که به صورت زیر است

status : وضعیت تراکنش که می توانید true یا false باشد

message : پیام سیستم و خطاها از طریق این متغیر در دسترس است

amount : مبلغی است که کاربر پرداخت نموده است

توجه : در صورتی که تراکنش ناموفق باشد متغیر amount را دریافت نخواهید کرد

حال چه تراکنشی موفق است ؟ در صورتی که مقدار status برابر با true باشد و مقدار message برابر با OK باشد تراکنش موفق بوده است و باید کالا و خدمات تحویل مشتری گردد

توجه : در صورتی که مقدار status برابر با true و مقدار message برابر با COMMIT باشد نشان دهنده آن است که تراکنش موفق بوده است و قبلاً کالا و خدمات برای این تراکنش تحویل داده شده است

message شرح پیام
merchantId Is Empty کد پذیرنده خالی است
amount Is Empty مبلغ خالی است
amount Is Not Numeric مبلغ عددی نیست
currency Is Not Valid واحد پولی نامتعبر است
amount Is Less Than 1,000 IRR مبلغ کمتر از 1,000 ریال است
callbackURL Is Empty آدرس بازگشت خالی است
callbackURL Is More Than 2048 Characters آدرس بازگشت بیشتر از 2048 کارکتر است
pspId Is Not Valid کد بانک نامعتبر است
amount Is Less Than 1 USD OR 32,000 IRR مبلغ کمتر از یک دلار یا 32,000 ریال است
amount Is More Than 100 USD مبلغ بیشتر از 100 دلار است
description Is Empty توضیحات خالی است
dscription Is More Than 2048 Characters توضیحات بیشتر از 2048 کارکتر است
dscription Is Not UTF-8 توضحیات UTF-8 نیست
merchantId Is Not Valid کد پذیرنده نا معتبر است
User Is Not Active کاربر فعال نیست
Unacceptable callbackURL آدرس بازگشت قابل قبول نیست
URL Is Not Valid Web Address آدرس یک وب آدرس معتبر نیست
New website was registered سایت جدید ثبت شد
Unknown Error خطای ناشناخته
Payment Gateway Disabled درگاه پرداخت غیر فعال است
Iranian PSP Payments Disabled درگاه‌های ایرانی غیر فعال است
Invalid IP آی پی نا معتبر
Payment request accepted درخواست پرداخت قبول شد
authority Is Empty کد یکتا خالی است
Invalid Transaction تراکنش نا معتبر
Failed Transaction تراکنش ناموفق
OK تراکنش موفق تایید شده
COMMIT تراکنش موفق کامیت شده