نسخه 3 مستندات نسخه 3
توضیحات
در نسخه شماره سه ما تغییرات خیلی زیادی داشتیم، از نام پکیج گرفته تا نحوه کار آن. در این نسخه نام پکیج از IPay به PoolPort تغییر کرد. همچنین نحوه کار با درگاهها بسیار ساده شده است، بطوریکه تنها با یک API یکسان میتوانید به تمام درگاههای موجود در پکیج متصل شوید. همچنین در این نسخه درگاههای جدیدی نیز به پکیج اضافه شده است.
فایل تنظیمات پکیج
در این فایل شما میتوانید تمام اطلاعات و تنظیمات مورد نیاز برای پکیج را وارد کنید. مسیر پیشفرض فایل در کنار پوشه vendor و با نام poolport.php است، اما شما میتوانید این فایل را در هر مسیری که میخواهید قرار بدهید و آدرس را در هنگام ساخت شی از کلاس به PoolPort بدهید.
<?php
return array(
//-------------------------------
// Timezone for insert dates in database
// If you want PoolPort not set timezone, just leave it empty
//--------------------------------
'timezone' => 'Asia/Tehran',
//--------------------------------
// Soap configuration
//--------------------------------
'soap' => array(
'attempts' => 2 // Attempts if soap connection is fail
),
//--------------------------------
// Database configuration
//--------------------------------
'database' => array(
'host' => '127.0.0.1',
'dbname' => '',
'username' => '',
'password' => '',
'create' => true // For first time you must set this to true for create tables in database
),
//--------------------------------
// Zarinpal gateway
//--------------------------------
'zarinpal' => array(
'merchant-id' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
'type' => 'zarin-gate', // Types: [zarin-gate || normal]
'callback-url' => 'http://www.example.org/result',
'server' => 'germany', // Servers: [germany || iran]
'email' => 'email@gmail.com',
'mobile' => '09xxxxxxxxx',
'description' => 'description',
),
//--------------------------------
// Mellat gateway
//--------------------------------
'mellat' => array(
'username' => '',
'password' => '',
'terminalId' => 0000000,
'callback-url' => 'http://www.example.org/result'
),
//--------------------------------
// Payline gateway
//--------------------------------
'payline' => array(
'api' => 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'callback-url' => 'http://www.example.org/result'
),
//--------------------------------
// Sadad gateway
//--------------------------------
'sadad' => array(
'merchant' => '',
'transactionKey'=> '',
'terminalId' => 000000000,
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// JahanPay gateway
//--------------------------------
'jahanpay' => array(
'api' => 'xxxxxxxxxxx',
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// Parsian gateway
//--------------------------------
'parsian' => array(
'pin' => 'xxxxxxxxxxxxxxxxxxxx',
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// Pasargad gateway
//--------------------------------
'pasargad' => array(
'merchant-code' => '9999999',
'terminal-code' => '999999',
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// Saderat gateway
//--------------------------------
'saderat' => array(
'merchant-id' => '999999999999999',
'terminal-id' => '99999999',
'public-key' => __DIR__.'/saderat-public-key.pem',
'private-key' => __DIR__.'/saderat-private-key.pem',
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// IranKish gateway
//--------------------------------
'irankish' => array(
'merchant-id' => 'xxxx',
'sha1-key' => 'xxxxxxxxxxxxxxxxxxxx',
'description' => 'description',
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// Simulator gateway
//--------------------------------
'simulator' => array(
'callback-url' => 'http://example.org/result'
),
//--------------------------------
// Saman gateway
//--------------------------------
'saman' => array(
'merchant-id' => 'xxxxx',
'callback-url' => 'http://example.org/result'
),
// Pay gateway
//--------------------------------
'pay' => array(
'api' => 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'callback-url' => 'http://www.example.org/result'
),
// JiBit gateway
//--------------------------------
'jibit' => array(
'merchant-id' => 'xxxx',
'password' => 'xxxxxxxxxx',
'callback-url' => 'http://www.example.org/result',
'user-mobile' => '09xxxxxxxx'
)
);
-
اگر میخواید
timezoneتوسط PoolPort تنظیم شود، این مقدار را وارد کنید، در غیر اینصورت این مقدار را خالی رها کنید. -
مقدار
attemptsدرsoapمشخص کننده تعداد تلاش در زمانی که ارتباط با سرور soap برقرار نمیشود، است. -
تنظیمات
databaseبرای اتصال به پایگاه داده است. در صورتی که قسمتcreateفعال (true) باشد، در هر بار استفاده از PoolPort، پکیج چک میکند که آیا جداول پکیج ایجاد شده است یا خیر، در صورتی که موجود نبودند، خود پکیج به صورت خودکار آنها را نصب میکند. پس توجه داشته باشید که در اولین استفاده از پکیج این گزینه راtrueکنید. -
دیگر قسمتها نیز مخصوص هر درگاه است، که در صورت استفاده از هر کدام از آنها، ابتدا تنظیمات آنها را پر کنید.
اتصال به درگاه
تنها با استفاده از کد زیر میتوانید به درگاه مورد نظر متصل شوید:
<?php
use PoolPort\PoolPort;
$poolPort = new PoolPort(PoolPort::P_MELLAT);
try {
$refId = $poolPort->set(1000)->ready()->refId();
// Your code here
$poolPort->redirect();
} catch (Exception $e) {
echo $e->getMessage();
}
-
در کد بالا به درگاه بانک ملت متصل میشوید. برای متصل شدن به درگاههای دیگر باید مقدار پارامتر اول را در هنگام ساختن کلاس تغییر دهید:
- بانک ملت
P_MELLAT - بانک ملی با عنوان سداد
P_SADAD - بانک صادرات
P_SADERAT - بانک پارسیان
P_PARSIAN - بانک پاسارگاد - تست نشده
P_PASARGAD - درگاه زرین پال
P_ZARINPAL - درگاه جهانپی
P_JAHANPAY - درگاه پیلاین
P_PAYLINE - درگاه ایران کیش
P_IRANKISH - بانک سامان
P_SAMAN - درگاه پی دات آی آر
P_PAY - درگاه جیبیت
P_JIBIT
- بانک ملت
-
اگر فایل تنظیمات را در محل پیشفرض قرار ندادید میتوانید، آدرس آن را به عنوان پارامتر دوم در هنگام ساختن کلاس بدهید.
<?php
$poolPort = new PoolPort(PoolPort::P_MELLAT, '../../poolport.php');
-
با استفاده از متد
setمیتوانید مقدار هزینه را به ریال وارد کنید. توجه کنید که در تمام درگاهها این مقدار باید به ریال وارد شود. -
پس از تنظیم هزینه باید متد
readyرا فراخوانی کنید. این متد چک میکند که آیا همه چیز برای متصل شدن به درگاه آماده است یا خیر. -
پس از فراخوانی متد
readyمیتوانید به درگاهredirectکنید. اما در کد بالا مشاهده میکنید که ما ابتدا مقدارrefIdرا دریافت کرده و سپس به درگاه تغییر مسیر میدهیم. مقدار ref id یک مقداری است که هر درگاه برای هر عملیات پرداخت در نظر میگرد. -
در صورت وقوع هر نوع خطا پکیج
Exceptionبرمیگرداند، به همین دلیل شما حتما باید کدهای مربوط به پکیج را در بلاک{}try{}catchقرار دهید.
برگشت به سایت
بعد از برگشت کاربر به سایت، تنها با استفاده از کد زیر میتوانید عملیات پرداخت را تایید کنید.
<?php
use PoolPort\PoolPort;
try {
$poolPort = new PoolPort;
$trackingCode = $poolPort->verify()->trackingCode();
$refId = $poolPort->refId();
$cardNumber = $poolPort->cardNumber();
// Your code here
} catch (Exception $e) {
echo $e->getMessage();
}
-
برای تایید اینکه آیا کاربر مبلغ مورد نظر را پرداخت کرده است یا خیر، باید متد
verifyرا فراخوانی کنید. در صورتی که کاربر مبلغ مورد نظر را پرداخت نکرده باشد، و یا هر نوع مشکلی در انجام تایید پرداخت بوجود آمده باشد، پکیجExceptionبرمیگرداند و مانع اجرا شدن کدهای بعدی خواهد شد. - متد
trackingCodeبرای گرفتن شماره رهگیری است. - متد
refIdبرای گرفتن مقدار ref id است. - متد
cartNumberبرای گرفتن شماره کارت کاربر است. توجه کنید که این متد در بعضی از درگاهها به دلیل پشتیبانی نکردن درگاه، مقدار خالی برمیگرداند.
Exceptions
در زمان بازگشت کاربر به سایت، ممکن است Exceptionهای مختلفی رخ بدهد:
- کاربر ممکن است برای دومین یا چندمین بار سعی بر ارسال داده از طرف بانک به سایت داشته باشد (
RetryException) - ممکن است اطلاعات بازگشتی درست نباشد و در اینجا ممکن است چنین درگاههی در سایت موجود نباشد (
PortNotFoundException) - ممکن است اطلاعات بازگشتی به سایت درست نباشد و در اینجا ممکن است آدرس بازگشت به سایت اشتباه باشد (
InvalidRequestException) - ممکن است اطلاعات بازگشتی به سایت درست نباشد و در اینجا ممکن است چنین رکورد پرداختی موجود نباشد. (
NotFoundTransactionException) - ممکن است کاربر از انجام پرداخت منصرف شده باشد. (
Exception)
شما میتوانید تمام این Exceptionها را به صورت زیر Handle کنید:
<?php
use PoolPort\PoolPort;
use PoolPort\Exceptions\RetryException;
use PoolPort\Exceptions\PortNotFoundException;
use PoolPort\Exceptions\InvalidRequestException;
use PoolPort\Exceptions\NotFoundTransactionException;
try {
$poolPort = new PoolPort;
$trackingCode = $poolPort->verify()->trackingCode();
$refId = $poolPort->refId();
$cardNumber = $poolPort->cardNumber();
// Your code here
} catch (RetryException $e) {
echo 'RetryException';
} catch (PortNotFoundException $e) {
echo 'PortNotFoundException';
} catch (InvalidRequestException $e) {
echo 'InvalidRequestException';
} catch (NotFoundTransactionException $e) {
echo 'NotFoundTransactionException';
} catch (Exception $e) {
echo $e->getMessage();
}
متد setConfig
با استفاده از این متد میتوانید تنظیمات درون فایل poolport.php را به ازای هر درخواست تغییر دهید.
برای مثال در کد زیر آدرس callback درگاه ملت را تغییر دادیم.
<?php
$poolPort = new PoolPort(PoolPort::P_MELLAT);
$poolPort->setConfig('mellat.callback-url', 'another url');
توجه کنید که استفاده از این متد برای تغییر تنظیمات database و timezone تاثیری ندارد.
متد transactionId
توسط این متد میتوانید آیدی متناظر transaction را در جدول poolport_transactions بدست آورید.
<?php
$poolPort = new PoolPort(PoolPort::P_MELLAT);
try {
$refId = $poolPort->set(1000)->ready()->refId();
$transactionId = $poolPort->transactionId();
// Your code here
$poolPort->redirect();
} catch (Exception $e) {
echo $e->getMessage();
}
متد setGlobalCallbackUrl
تنها با فراخوانی این متد میتوانید آدرس بازگشت تمام درگاهها را به صورت یکجا تغییر دهید و نیازی به فراخوانی متد setConfig برای هر درگاه نیست.
<?php
$port = new PoolPort(PoolPort::P_SIMULATOR);
$port->setGlobalCallbackUrl('another url');
$port->set(1000)->ready()->redirect();