توضیحات

در نسخه شماره سه ما تغییرات خیلی زیادی داشتیم، از نام پکیج گرفته تا نحوه کار آن. در این نسخه نام پکیج از 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();