tartan/laravel-online-payment

Iranian payment gateways handler for laravel applications

Laravel Iranian Online Payment Component

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., _(*1)

Here are a few short examples of what you can do: * create new transaction form your order model and generate bank form, _(*2)

 $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 / درگاه نکست پی, _(*3)

• ..., _(*4)

• 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+, _(*5)

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., _(*6)

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

If you choose development mode, Larapay use banktest.ir as it's payment gateway., _(*8)

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

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, _(*10)

For example create a POST route in routes folder, web.php like this:, _(*11)

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

then set the route name in .env file:, _(*12)

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., _(*13)

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

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:, _(*15)

1- create transaction

In your bank controller create a transaction for your order and generate bank for to transfer user to payment gateway., _(*16)

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:, _(*17)

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

You can modify bank forms in:, _(*18)

resources/views/vendor/larapy

3- handle callback

After payment, bank call you callback route, _(*19)

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:, _(*20)

$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, _(*21)

Gate information: * payment_method * bank_order_id * gate_name * gate_refid * gate_status * extra_params * additional_data, _(*22)

Order information: * amount * description * paid_at, _(*23)

LarapayTransaction

You can use LarapayTransaction model to find your transaction:, _(*24)

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., _(*25)

Security

If you discover any security related issues, please email a6oozar@gmail.com or milad.kian@gmail.com instead of using the issue tracker., _(*26)

Team

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

| | | | --- | --- | --- | --- | Aboozar Ghaffari | Milad Kianmehr | Sina Miandashti | XShaan, _(*28)

Support This Project

Please contribute in package completion. This is the best support., _(*29)

License

The Laravel Online Payment Module is open-sourced software licensed under the MIT license, _(*30)