نسخه 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();