php-monsters/laravel-online-payment

Iranian payment gateways handler for laravel applications

v8.1.9 2023-12-03 10:29 UTC

Requires

• php: >=7.4
• ext-bcmath: *
• ext-json: *
• ext-simplexml: *
• ext-soap: *
• illuminate/contracts: >=7.0
• illuminate/database: >=7.0
• illuminate/http: >=7.0
• illuminate/routing: >=7.0
• illuminate/support: >=7.0
• illuminate/view: >=7.0
• php-monsters/laravel-xlog: ^1.3.0

Requires (Dev)

• mockery/mockery: ^1.0
• orchestra/testbench: ^3.8|^4.0|^5.0
• phpunit/phpunit: ^7.5|^8.0

MIT

• Aboozar Ghaffari <samuraee>
• Milad Kianmehr

• payment
• gateway
• Bank
• online payment
• iran
• shetab

README

Online Payment Module handler for Laravel 5+ known as LaraPay component completely compatible with BankTest sandbox. Larapay integrated all Iranian payment gateways into one component.

Here are a few short examples of what you can do:

• create new transaction form your order model and generate bank form

 $transaction = $order->createTransaction(Bank::MELLAT);
 $form = $transaction->generateForm();

• handle gateway callback (verify/settle/...)

 $transaction = Larapay::verifyTransaction($request);
 //if the gateway supports reverse method
 $transaction->reverseTransaction();
 $order = $transaction->model;

• get order transaction information

 $allTransactions = $order->transations;
 $accomplishedTransactions = $order->accomplishedTransactions;
 $isPaid = $order->isPaid();
 $paidAmount = $order->paidAmount();

Currenctly supports:

• Mellat Bank Gateway - درگاه بانک ملت لاراول

• Saman Bank Gateway - درگاه بانک سامان لاراول

• Saderat/Sepehr Pay Bank Gateway - درگاه بانک صادرات / سپهر

• Pasargad Bank Gateway - درگاه بانک پاسارگاد لاراول

• Parsian Bank Gateway - درگاه بانک پارسیان لاراول

• Melli/Sadad Bank Gateway (Sadad) - درگاه بانک ملی / سداد لاراول

• Pay.ir Gateway / درگاه پرداخت پی

• Zarinpal Gateway / درگاه پرداخت زرین پال

• IDPay Gateway / درگاه آیدی پی

• Zibal Gateway / درگاه زیبال

• nextpay Gateway / درگاه نکست پی

• ...

• Other gateways, coming soon... لطفا شما هم در تکمیل پکیج مشارکت کنید

But what is B‌anktest sandbox?

• BankTest is a sandbox service for all Iranian online payment gateways
• بانک تست یک سرویس شبیه ساز درگاه های پرداخت آنلاین ایرانی برای اهداف توسعه و تست نرم افزار می باشد

Requirements

Larapay Version 6+ required PHP 7+

Installation

1. Installing via composer

composer require php-monsters/laravel-online-payment

1. Add package service provider to your app service providers (only for Laravel < 5.5):

PhpMonsters\Larapay\LarapayServiceProvider::class,
PhpMonsters\Log\XLogServiceProvider::class,

1. Add package alias to your app aliases (only for Laravel < 5.5):

'Larapay' => PhpMonsters\Larapay\Facades\Larapay::class,
'XLog'    => PhpMonsters\Log\Facades\XLog::class,

1. Publish package assets and configs

php artisan vendor:publish --provider="PhpMonsters\Larapay\LarapayServiceProvider"

1. Run migration

php artisan migrate

Configuration

If you complete installation step correctly, you can find Larapay config file as larapay.php in you project config file.

For sandbox (banktest) you should set LARAPAY_MODE=development in your .env file otherwise set LARAPAY_MODE=production

If you choose development mode, Larapay use banktest.ir as it's payment gateway.

Set your gateway(s) configs in your .env file. Here are some example:

LARAPAY_MODE=development

SAMAN_MERCHANT_ID=bmcf****
SAMAN_MERCHANT_PASS=98221***

MELLAT_USERNAME=user***
MELLAT_PASSWORD=80714***
MELLAT_TERMINAL_ID=747

Setup callback route

you should create a route for handling callback from bank and set your route name in .env

For example create a POST route in routes folder, web.php like this:

Route::post('payment/callback', 'YourController@handleCallback')->name('payment.callback');

then set the route name in .env file:

LARAPAY_PAYMENT_CALLBACK=payment.callback

Usage

Prepare payable model

Use Payable trait in your order model or any other model like user which will get payment feature and implement it.

You can impalement getAmount() method to return Iranian Rail amount of your model.

use PhpMonsters\Larapay\Payable;

class Order extends Model 
{
    use Payable;

    public function getAmount(){
        return intval($this->amount) * 10;
    }   

}

Now you just have 3 steps to complete your payment:

1- create transaction

In your bank controller create a transaction for your order and generate bank for to transfer user to payment gateway.

use PhpMonsters\Larapay\Models\Enum\Bank;

class BankController extends Controller
{
    public function index()
    {
        //your logic and prepare your order
        // ...

        //if you implement getAmount() method you can set amount to null
        $amount = 1200000;  //Rial at least 1000 
        //order or user description
        $description = 'I pay my order with Larapay <3';
        //some additional data that you need store on transaction
        $additionalData = [];
        //create transaction 
        $transaction = $order->createTransaction(Bank::MELLAT, $amount, $description, $additionalData);
        
        //auto submit bank form and transfer user to gateway
        $autoSubmit = true;
        //callback route name. if you set it on your .env file you can set this to null
        $callbackRouteName = 'payment.callback';
        //adapter config
        $adapterConfig = [];
        //generate bank form
        $form = $transaction->generateForm($autoSubmit, $callbackRouteName, $adapterConfig);
        
        return view('go-to-bank',[
            'form' => $form,
        ]);
    }
}

2- show bank transfer form

Now you can show you $form in your go-to-bank view file:

<div>
    {!! $form !!}
</div>

You can modify bank forms in:

resources/views/vendor/larapy

3- handle callback

After payment, bank call you callback route

use Illuminate\Http\Request;
use PhpMonsters\Larapay\Facades\Larapay;

class YourController extends Controller
{
    public function handleCallback(Request $request)
    {
         try{
            $adapterConfig = [];
            $transaction = Larapay::verifyTransaction($request, $adapterConfig);
            $order = $transaction->model;
            //transaction done. payment is successful         
         } catch (\Exception $e){
            // transaction not complete!!!
            // show error to your user
         }
    }
}

If you want to revers transaction and your bank support it, you can do this way:

$transaction->reverseTransaction();

Methods

Methods available in Paybel trait and your order model:

• $order->transactions : get all transactions of this model
• $order->accomplishedTransactions: get all accomplished transactions
• $order->isPaid(): return true if this model has at least one accomplished transaction
• $order->paidAmount(): return sum of accomplished transactions amount in Rial
• $order->createTransaction( $paymentGateway, $amount = null, $description = null, array $additionalData = [] ): create a transaction.

Methods available in LarapayTransaction model:

• $transaction->model: return the model that create this transaction. for example $order
• $transaction->reverseTransaction(): reverse transaction and get back money to user. (if bank support reverse transaction)
• $transaction->generateForm($autoSubmit = false, $callback = null): generate bank transfer form
• $transaction->gatewayHandler(): get gatewayHandler for advance use.

Fields available in LarapayTransaction model:

• id
• created_at
• updated_at

Status in boolean:

• accomplished
• verified
• after_verified
• reversed
• submitted
• approved
• rejected

Gate information:

• payment_method
• bank_order_id
• gate_name
• gate_refid
• gate_status
• extra_params
• additional_data

Order information:

• amount
• description
• paid_at

LarapayTransaction

You can use LarapayTransaction model to find your transaction:

use PhpMonsters\Larapay\Models\LarapayTransaction;

public function getTransaction($transactionId){

    //find single transaction by transaction id
    $transaction = LarapayTransaction::find($transactionId);
    
    //get all accomplished transaction
    $accomplishedTransactions = LarapayTransaction::where('accomplished',true)->get();
    
    //get all reversed transaction
    $reversedTransactions = LarapayTransaction::where('reversed',true)->get();
}

This class use SoftDeletes. you can call delete() on your transaction model to softDelete it or forceDelete() to truly remove it from your database.

Security

If you discover any security related issues, please email [e-mail] or [e-mail] instead of using the issue tracker.

Team

This component is developed by the following person(s) and a bunch of awesome contributors.

Support This Project

Please contribute in package completion. This is the best support.

License

The Laravel Online Payment Module is open-sourced software licensed under the MIT license