README-FA.md

پکیج درگاه پرداخت برای لاراول

این پکیج برای پرداخت آنلاین توسط درگاه‌های مختلف در لاراول ایجاد شده است.

این پکیج با درگاه‌های پرداخت مختلفی کار میکنه. در صورتی که درگاه مورد نظرتون رو در لیست درایورهای موجود پیدا نکردید می‌تونید برای درگاهی که استفاده می‌کنید درایور مورد نظرتون رو بسازید.

درصورتی که از PHP استفاده میکنید میتونید از پکیج shetabit/multipay استفاده کنید.

• داکیومنت فارسی
• english documents
• 中文文档

در صورتی که از این پکیج خوشتون آمده و ازش استفاده می‌کنید می‌تونید با پرداخت مبلغ اندکی من رو حمایت کنید تا این پکیج رو بیشتر توسعه بدم و درگاه‌های جدیدتری بهش اضافه کنم.

به منظور کمک مالی کلیک کنید 😎

در صورتی که نیاز به آموزش دارید میتونید یه نگاهی به لینک زیر بندازید

• آموزش ویدیویی پرداخت و خرید در لاراول

لیست محتوا

• درایور های موجود
• نصب
• تنظیمات
• طریقه استفاده
  • کار با صورتحساب ها
  • ثبت درخواست برای پرداخت صورتحساب
  • پرداخت صورتحساب
  • اعتبار سنجی پرداخت
  • ایجاد درایور دلخواه
  • متدهای سودمند
• تغییرات
• مشارکت کننده ها
• امنیت
• توسعه دهندگان
• لایسنس

درایورهای موجود

• آتی‌پی ✔️

• آقای پرداخت ✔️

• ازکی‌وام (پرداخت اقساطی) ✔️

• آسان‌پرداخت ✔️

• اعتبارینو (پرداخت اقساطی) ✔️

• امیدپی ✔️

• آی‌دی‌پی ✔️

• ایران‌کیش ✔️

• به‌پرداخت (ملت) ✔️

• بیت‌پی ✔️

• دیجی‌پی ✔️

• فن‌آوا‌کارت ✔️

• لوکال ✔️

• جیبیت ✔️

• نکست‌پی ✔️

• پارسیان ✔️

• پاسارگاد ✔️

• پی‌آی‌آر ✔️

• پی‌فا ✔️

• پی‌پال (به زودی در ورژن بعدی اضافه می‌شود)

• پی‌پینگ ✔️

• پی‌استار ✔️

• پولام ✔️

• رایان‌پی ✔️

• سداد (ملی) ✔️

• سامان ✔️

• سپ (درگاه الکترونیک سامان) کشاورزی و صادرات ✔️

• سپهر (صادرات) ✔️

• سپرده ✔️

• سیزپی ✔️

• تومن ✔️

• وندار ✔️

• والتا ✔️

• یک‌پی ✔️

• زرین‌پال ✔️

• زیبال ✔️

• درایورهای دیگر ساخته خواهند شد یا اینکه بسازید و درخواست merge بدید.

در صورتی که درایور مورد نظرتون موجود نیست, می‌تونید برای درگاه پرداخت موردنظرتون درایور بسازید.

نصب

نصب با استفاده از کامپوزر

composer require shetabit/payment

تنظیمات

درصورتی که از Laravel 5.5 یا ورژن های بالاتر استفاده می‌کنید نیازی به انجام تنظیمات providers و alias نخواهید داشت.

درون فایل config/app.php دستورات زیر را وارد کنید

// In your providers array.
'providers' => [
    ...
    Shetabit\Payment\Provider\PaymentServiceProvider::class,
],

// In your aliases array.
'aliases' => [
    ...
    'Payment' => Shetabit\Payment\Facade\Payment::class,
],

سپس دستور php artisan vendor:publish را اجرا کنید تا فایل config/payment.php درون دایرکتوری تنظیمات لاراول قرار بگیرد.

درون فایل تنظیمات در قسمت default driver می‌توانید درایوری که قصد استفاده از ان را دارید قرار دهید تا تمامی پرداخت ها از آن طریق انجام شود.

// Eg. if you want to use zarinpal.
'default' => 'zarinpal',

سپس تنظیمات مرتبط با درایوری که قصد استفاده از ان را دارید انجام دهید

'drivers' => [
    'zarinpal' => [
        // Fill all the credentials here.
        'apiPurchaseUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentRequest.json',
        'apiPaymentUrl' => 'https://www.zarinpal.com/pg/StartPay/',
        'apiVerificationUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentVerification.json',
        'merchantId' => '',
        'callbackUrl' => 'http://yoursite.com/path/to',
        'description' => 'payment in '.config('app.name'),
    ],
    ...
]

طریقه استفاده

در تمامی پرداخت ها اطلاعات پرداخت درون صورتحساب شما نگهداری میشود. برای استفاده از پکیج ابتدا نحوه ی استفاده از کلاس Invoice به منظور کار با صورتحساب ها را توضیح میدهیم.

کار با صورتحساب ها

قبل از انجام هرکاری نیاز به ایجاد یک صورتحساب دارید. برای ایجاد صورتحساب می‌توانید از کلاس Invoice استفاده کنید.

درون کد خودتون به شکل زیر عمل کنید:

// At the top of the file.
use Shetabit\Multipay\Invoice;
...

// Create new invoice.
$invoice = new Invoice;

// Set invoice amount.
$invoice->amount(1000);

// Add invoice details: There are 4 syntax available for this.
// 1
$invoice->detail(['detailName' => 'your detail goes here']);
// 2 
$invoice->detail('detailName','your detail goes here');
// 3
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);
// 4
$invoice->detail('detailName1','your detail1 goes here')
        ->detail('detailName2','your detail2 goes here');

متدهای موجود برای کار با صورتحساب ها:

• uuid: یک ایدی یونیک برای صورتحساب تنظیم می‌کند
• getUuid: ایدی یونیک صورتحساب را برمی‌گرداند
• detail: توضیحات یا مواردی که مرتبط به صورتحساب است را به صورتحساب اضافه می‌کند
• getDetails: تمامی موارد مرتبطی که به صورتحساب افزوده شده است را برمی‌گرداند
• amount: مقدار هزینه‌ای که باید پرداخت شود را مشخص می‌کند
• getAmount: هزینه‌ی صورتحساب را برمی‌گرداند
• transactionId: شماره تراکنش صورتحساب را مشخص می‌کند
• getTransactionId: شماره تراکنش صورتحساب را برمی‌گرداند
• via: درایوری که قصد پرداخت صورتحساب با آن را داریم مشخص می‌کند
• getDriver: درایور انتخاب شده را برمی‌گرداند

ثبت درخواست برای پرداخت صورتحساب

به منظور پرداخت تمامی صورتحساب ها به یک شماره تراکنش بانکی یا transactionId نیاز خواهیم داشت. با ثبت درخواست به منظور پرداخت میتوان شماره تراکنش بانکی را دریافت کرد:

// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Payment\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
Payment::purchase($invoice,function($driver, $transactionId) {
	// We can store $transactionId in database.
});

// Purchase method accepts a callback function.
Payment::purchase($invoice, function($driver, $transactionId) {
    // We can store $transactionId in database.
});

// You can specify callbackUrl
Payment::callbackUrl('http://yoursite.com/verify')->purchase(
    $invoice, 
    function($driver, $transactionId) {
    	// We can store $transactionId in database.
	}
);

پرداخت صورتحساب

با استفاده از شماره تراکنش یا transactionId میتوانیم کاربر را به صفحه ی پرداخت بانک هدایت کنیم:

// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Payment\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);
// Purchase and pay the given invoice.
// You should use return statement to redirect user to the bank page.
return Payment::purchase($invoice, function($driver, $transactionId) {
    // Store transactionId in database as we need it to verify payment in the future.
})->pay()->render();

// Do all things together in a single line.
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
    	// Store transactionId in database.
        // We need the transactionId to verify payment in the future.
	}
)->pay()->render();

// Retrieve json format of Redirection (in this case you can handle redirection to bank gateway)
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
    	// Store transactionId in database.
        // We need the transactionId to verify payment in the future.
	}
)->pay()->toJson();

اعتبار سنجی پرداخت

بعد از پرداخت شدن صورتحساب توسط کاربر, بانک کاربر را به یکی از صفحات سایت ما برمیگردونه و ما با اعتبار سنجی میتونیم متوجه بشیم کاربر پرداخت رو انجام داده یا نه!

// At the top of the file.
use Shetabit\Payment\Facade\Payment;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
...

// You need to verify the payment to ensure the invoice has been paid successfully.
// We use transaction id to verify payments
// It is a good practice to add invoice amount as well.
try {
	$receipt = Payment::amount(1000)->transactionId($transaction_id)->verify();

    // You can show payment referenceId to the user.
    echo $receipt->getReferenceId();

    ...
} catch (InvalidPaymentException $exception) {
    /**
    	when payment is not verified, it will throw an exception.
    	We can catch the exception to handle invalid payments.
    	getMessage method, returns a suitable message that can be used in user interface.
    **/
    echo $exception->getMessage();
}

در صورتی که پرداخت توسط کاربر به درستی انجام نشده باشه یک استثنا از نوع InvalidPaymentException ایجاد میشود که حاوی پیام متناسب با پرداخت انجام شده است.

ایجاد درایور دلخواه:

برای ایجاد درایور جدید ابتدا نام (اسم) درایوری که قراره بسازید رو به لیست درایور ها اضافه کنید و لیست تنظیات مورد نیاز را نیز مشخص کنید.

'drivers' => [
    'zarinpal' => [...],
    'my_driver' => [
        ... // Your Config Params here.
    ]
]

کلاس درایوری که قصد ساختنش رو دارید باید کلاس Shetabit\Payment\Abstracts\Driver رو به ارث ببره.

به عنوان مثال:

namespace App\Packages\PaymentDriver;

use Shetabit\Multipay\Abstracts\Driver;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
use Shetabit\Multipay\{Contracts\ReceiptInterface, Invoice, Receipt};

class MyDriver extends Driver
{
    protected $invoice; // Invoice.

    protected $settings; // Driver settings.

    public function __construct(Invoice $invoice, $settings)
    {
        $this->invoice($invoice); // Set the invoice.
        $this->settings = (object) $settings; // Set settings.
    }

    // Purchase the invoice, save its transactionId and finaly return it.
    public function purchase() {
        // Request for a payment transaction id.
        ...
            
        $this->invoice->transactionId($transId);
        
        return $transId;
    }
    
    // Redirect into bank using transactionId, to complete the payment.
    public function pay() {
        // It is better to set bankApiUrl in config/payment.php and retrieve it here:
        $bankUrl = $this->settings->bankApiUrl; // bankApiUrl is the config name.

        // Prepare payment url.
        $payUrl = $bankUrl.$this->invoice->getTransactionId();

        // Redirect to the bank.
        return redirect()->to($payUrl);
    }
    
    // Verify the payment (we must verify to ensure that user has paid the invoice).
    public function verify(): ReceiptInterface {
        $verifyPayment = $this->settings->verifyApiUrl;
        
        $verifyUrl = $verifyPayment.$this->invoice->getTransactionId();
        
        ...
        
        /**
			Then we send a request to $verifyUrl and if payment is not valid we throw an InvalidPaymentException with a suitable message.
        **/
        throw new InvalidPaymentException('a suitable message');
        
        /**
        	We create a receipt for this payment if everything goes normally.
        **/
        return new Receipt('driverName', 'payment_receipt_number');
    }
}

بعد از اینکه کلاس درایور خودتون رو ایجاد کردید به فایل Config/payment.php برید و درایور خودتون رو در قسمت map اضافه کنید.

'map' => [
    ...
    'my_driver' => App\Packages\PaymentDriver\MyDriver::class,
]

نکته: دقت کنید کلیدی که قسمت map قرار میدهید باید همنام با نامی باشد که در قسمت drivers قرار داده اید.

متدهای سودمند

• callbackUrl: با استفاده از این متد به صورت داینامیک می‌توانید ادرس صفحه ای که بعد از پرداخت آنلاین کاربر به ان هدایت میشود را مشخص کنید

// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Payment\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
Payment::callbackUrl($url)->purchase(
    $invoice, 
    function($driver, $transactionId) {
    // We can store $transactionId in database.
	}
);

• amount: به کمک این متد می‌توانید به صورت مستقیم هزینه صورتحساب را مشخص کنید

// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Payment\Facade\Payment;
...

// Purchase (we set invoice to null).
Payment::callbackUrl($url)->amount(1000)->purchase(
    null, 
    function($driver, $transactionId) {
    // We can store $transactionId in database.
	}
);

• via: به منظور تغییر درایور در هنگام اجرای برنامه مورد استفاده قرار میگیرد

// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Payment\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
Payment::via('driverName')->purchase(
    $invoice, 
    function($driver, $transactionId) {
    // We can store $transactionId in database.
	}
);

رویدادها

شما می‌توانید درون برنامه خود دو رویداد را ثبت و ضبط کنید

• InvoicePurchasedEvent: هنگامی که یک پرداخت به درستی ثبت شود این رویداد اتفاق می‌افتد.
• InvoiceVerifiedEvent: هنگامی که یک پرداخت به درستی وریفای شود این رویداد اتفاق می‌افتد

تغییرات

برای مشاهده آخرین تغییرات انجام شده در پکیج قسمت تغییرات را بررسی کنید.

مشارکت کننده ها

برای مشاهده لیست مشارکت کننده ها CONTRIBUTING and CONDUCT را بررسی کنید.

امنیت

در صورتی که مشکل امنیتی در پکیج پیدا کردید به منظور رفع مشکل با ایمیل khanzadimahdi@gmail.com در ارتباط باشید.

توسعه دهندگان

• Mahdi khanzadi
• All Contributors

لایسنس

توسعه و تولید تحت لایسنس MIT است. برای اطلاعات بیشتر فایل لایسنس را مطالعه کنید.