Laravel Payze.io Integration Package

This package allows you to process payments with Payze.io from your Laravel application.

Table of Contents

• Installation
  • API Keys
  • Define Routes
• Config
  • Log
  • SSL Verification
  • Routes
  • Views
  • Transactions Table
  • Logs Table
  • Card Tokens Table
  • API Key
  • API Secret
• Payments & Requests
  • Just Pay
  • Add (Save) Card
  • Pay with a Saved Card
  • Commit
  • Refund
  • Transaction Info
  • Merchant's Balance
• Payment Request Options
  • Amount
  • Currency
  • Language
  • Preauthorize
  • Associated Model
  • Split Money
  • Raw Data
• Controller
• Events
• Relationships
  • Transactions Relationship
  • Cards Relationship
• Models
  • Transaction Model
  • Card Token Model
  • Log Model
• Abandoned Transactions
• Authors

Installation

composer require payzeio/laravel-payze

For Laravel <= 5.4

If you're using Laravel 5.4 or lower, you have to manually add a service provider in your config/app.php file. Open config/app.php and add PayzeServiceProvider to the providers array.

'providers' => [
    # Other providers
    PayzeIO\LaravelPayze\PayzeServiceProvider::class,
],

Publish migrations and config by running:

php artisan vendor:publish --provider="PayzeIO\LaravelPayze\PayzeServiceProvider"

And run migrations:

php artisan migrate

API Keys

Go to Payze.io website and generate an API key. Place key and secret to .env file:

PAYZE_API_KEY=PayzeApiKey
PAYZE_API_SECRET=PayzeApiSecret

Define Routes

You have to define success and fail routes in your application in order to finalize transactions. Go to your web.php (or wherever you store routes) and add the following:

routes() function takes 3 optional parameters:

Controller: Controller name, default: App\Http\Controller\PayzeController

Success Method: Success method name, default: success

Fail Method: Fail method name, default: fail

use PayzeIO\LaravelPayze\Facades\Payze;

// Other routes...

Payze::routes();

These routes will have the names payze.success and payze.fail. If you have defined them under some namespace, then you can update names in config. For example, if you defined payze routes in api.php and that file has the name api., then your routes will be api.payze.success and api.payze.fail. Update them in config/payze.php file, stored in routes array.

Config

The general variables are stored in config/payze.php file. More details:

Log

Enable/disable database detailed logging on every request/transaction. By default, the log is enabled on the local environment only. You can override the value from .env or directly from the config file.

SSL Verification

Enable/Disable SSL verification in Guzzle client to avoid SSL problems on some servers. Enabled by default.

Routes

Success and fail routes names, which are used to identify the finished transactions and update transaction status in the database.

Update route names only if you have defined routes in a different namespace (like api). For example you will have api.payze.success and api.payze.fail URLs.

Views

Success and fail view names, which are displayed after a transaction is complete. You can override them and use your own pages with your own layout.

By default, it uses an empty page with just status text (green/red colors) and a "return home" button.

Transactions Table

The name of the table in the database, which is used to store all of the transactions.

Logs Table

The name of the table in the database, which is used to store detailed logs about transactions and API requests.

Card Tokens Table

The name of the table in the database, which is used to store all of the saved card tokens.

API Key

API key of your Payze.io account.

API Secret

API secret of your Payze.io account.

Payments & Requests

All of the requests are sent by corresponding classes, which extends the same class (PayzeIO\LaravelPayze\Concerns\ApiRequest).

All requests are called statically by request() function (passing constructor data), then chain all of the needed data and then process().

Detailed instructions about needed data and options are in the next section.

Just Pay

If you need a one-time payment, then you should use the Just Pay function.

Parameters:

• Amount - float, required

Return: Illuminate\Http\RedirectResponse

use PayzeIO\LaravelPayze\Requests\JustPay;

return JustPay::request(1)
    ->for($order) // optional
    ->preauthorize() // optional
    ->process();

Add (Save) Card

Saving a card gives you a card token which you use for further manual charges without customer interaction. You can charge any amount and also save a card in one action, or you can set the amount to 0 to just save a card (Some banks may charge 0.1GEL and refund for saving a card).

Card tokens are saved in database and can be accessed by PayzeCardToken model or cards relationship.

After requesting a payment, a card token is created in a database with an inactive status. After a successful charge, the card token becomes active automatically.

IMPORTANT! If you want to associate a card token with the user and a transaction with an order, then you should use assignTo method, which receives a model instance of the owner of a card token.

Parameters:

• Amount - float, optional, default: 0

Methods:

• assignTo - Illuminate\Database\Eloquent\Model, optional, default: null

Return: Illuminate\Http\RedirectResponse

use PayzeIO\LaravelPayze\Requests\AddCard;

return AddCard::request(1)
    ->for($order) // transaction will be assigned to order
    ->assignTo($user) // optional: card token will be assigned to user. if not present, then will be assigned to order
    ->process();

Pay with a Saved Card

You can pay with a saved card token anytime without customer interaction.

Card tokens can be accessed by PayzeCardToken model or cards relationship. Filter tokens by active status (with active() scope)

Parameters:

• CardToken - PayzeIO\LaravelPayze\Models\PayzeCardToken, required
• Amount - float, optional, default: 0

Return: PayzeIO\LaravelPayze\Models\PayzeTransaction

use PayzeIO\LaravelPayze\Requests\PayWithCard;

// Get user's latest saved card
$card = $user->cards()->active()->latest()->firstOrFail();

return PayWithCard::request($card, 15)
    ->for($order) // optional
    ->process();

Commit

Commit (charge) a blocked (preauthorized) transaction.

Parameters:

• TransactionId - string|PayzeIO\LaravelPayze\Models\PayzeTransaction, required
• Amount - float, optional, default: 0, (can be partially charged). 0 will charge full amount

Return: PayzeIO\LaravelPayze\Models\PayzeTransaction

use PayzeIO\LaravelPayze\Requests\Commit;

return Commit::request($transaction)->process();

Refund

Refund a refundable transaction.

Parameters:

• TransactionId - string|PayzeIO\LaravelPayze\Models\PayzeTransaction, required
• Amount - float, optional, default: 0, (can be partially refunded). 0 will refund full amount

Return: PayzeIO\LaravelPayze\Models\PayzeTransaction

use PayzeIO\LaravelPayze\Models\PayzeTransaction;
use PayzeIO\LaravelPayze\Requests\Refund;

$transaction = PayzeTransaction::refundable()->latest()->firstOrFail();

return Refund::request($transaction)->process();

Transaction Info

Get transaction info and update in the database.

Parameters:

• TransactionId - string|PayzeIO\LaravelPayze\Models\PayzeTransaction, required

Return: PayzeIO\LaravelPayze\Models\PayzeTransaction

use PayzeIO\LaravelPayze\Models\PayzeTransaction;
use PayzeIO\LaravelPayze\Requests\GetTransactionInfo;

$transaction = PayzeTransaction::latest()->firstOrFail();

return GetTransactionInfo::request($transaction)->process();

Merchant's balance

Get balance info from the merchant's account.

Return: array

use PayzeIO\LaravelPayze\Requests\GetBalance;

return GetBalance::request()->process();

Payment Request Options

You can pass these parameters to all of the payment requests in Payze package.

Amount

All payment requests have an amount in the constructor, but also there is a separate method for changing the amount.

use PayzeIO\LaravelPayze\Requests\JustPay;

// Request 1 GEL originally
$request = JustPay::request(1);

// Some things happened, updating amount
return $request->amount(10)->process();

Currency

You can change your payment's currency by calling currency() function on the request. Default: GEL

See supported currencies in currencies enum file.

Recommended: Pass currency by using an enum instead of directly passing a string.

use PayzeIO\LaravelPayze\Enums\Currency;
use PayzeIO\LaravelPayze\Requests\JustPay;

return JustPay::request(1)->currency(Currency::USD)->process();

Language

You can change your payment page's language by calling language() function on the request. Default: ge

See supported languages in languages enum file.

Recommended: Pass language by using an enum instead of directly passing a string.

use PayzeIO\LaravelPayze\Enums\Language;
use PayzeIO\LaravelPayze\Requests\JustPay;

return JustPay::request(1)->language(Language::ENG)->process();

Preauthorize

Preauthorize method is used to block the amount for some time and then manually charge (commit) the transaction. For example, if you are selling products which have to be produced after the order, block (preauthorize) transaction on order and manually charge (commit) after your product are ready.

Associated Model

You can associate any Eloquent model to a transaction by calling for() function on the request. For example, pass an order instance to a payment request for checking the order's payment status after payment.

use App\Models\Order;
use PayzeIO\LaravelPayze\Requests\JustPay;

$order = Order::findOrFail($orderId);

return JustPay::request(1)->for($order)->process();

Split Money

You can split the money into different bank accounts. For example, you have a marketplace where users sell their products and you get a commission for that. You can simply split transferred money easily instead of manually transferring from a bank account to a seller on every order.

You have to call split() function on the request, which accepts list/array of PayzeIO\LaravelPayze\Objects\Split object(s).

Split object has three parameters: Amount, Receiver's IBAN, and Pay In (optional) (delay in days before transferring the money).

For example, the cost of a product is 20GEL. You have to get your commission (10%) and transfer the rest to a seller.

use PayzeIO\LaravelPayze\Objects\Split;
use PayzeIO\LaravelPayze\Requests\JustPay;

return JustPay::request(20)
    ->split(
        new Split(2, "Your IBAN"), // Transfer 2GEL immediately
        new Split(18, "Seller's IBAN", 3) // Transfer 18GEL after 3 days (for example, as an insurance before processing the order)
    )->process();

Raw Data

By default, when you request a payment, it will return a RedirectResponse. You can call raw() function and payment request will return the original data instead of a RedirectResponse.

use PayzeIO\LaravelPayze\Requests\JustPay;

$request = JustPay::request(20)->raw()->process();

log($request['transactionId']);

return $request['transactionUrl'];

Controller

Default controller should be published after running publish command from Installation section. You can add your custom logic to your controller in successResponse and failResponse methods. For example, you can set flash message, send notifications, mark order as complete or anything you want from that methods.

IMPORTANT! If you return any non-NULL value from successResponse and failResponse methods, then that response will be used on success/fail routes. Otherwise default logic will be used.

Events

Events are fired after successful or failed transactions. You can define listeners in your application in order to mark an order as paid, notify a customer or whatever you need.

Both events have $transaction property.

Paid Event: PayzeIO\LaravelPayze\Events\PayzeTransactionPaid

Failed Event: PayzeIO\LaravelPayze\Events\PayzeTransactionFailed

Relationships

You can add transactions and cards relationships to your models with traits to easily access associated entries.

Transactions Relationship

Add HasTransactions trait to your model.

use PayzeIO\LaravelPayze\Traits\HasTransactions;

class Order extends Model
{
    use HasTransactions;
}

Now you can access transactions by calling $order->transactions.

Cards Relationship

Add HasCards trait to your model.

use PayzeIO\LaravelPayze\Traits\HasCards;

class User extends Model
{
    use HasCards;
}

Now you can access saved cards by calling $user->cards.

Models

Transaction Model

You can access all transactions logged in the database by PayzeIO\LaravelPayze\Models\PayzeTransaction model.

Get all transactions:

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::all();

Paid Scope

Filter paid transactions with paid() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::paid()->get();

Unpaid Scope

Filter unpaid transactions with unpaid() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::unpaid()->get();

Completed Scope

Filter completed transactions with completed() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::completed()->get();

Incomplete Scope

Filter incomplete transactions with incomplete() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::incomplete()->get();

Refundable Scope

Filter refundable transactions with refundable() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::refundable()->get();

Non-Refundable Scope

Filter non-refundable transactions with nonrefundable() scope.

use PayzeIO\LaravelPayze\Models\PayzeTransaction;

PayzeTransaction::nonrefundable()->get();

Card Token Model

You can access all saved card tokens logged in the database by PayzeIO\LaravelPayze\Models\PayzeCardToken model.

Get all tokens:

use PayzeIO\LaravelPayze\Models\PayzeCardToken;

PayzeCardToken::all();

Active card tokens have card_mask attribute, which can be helpful for a user to choose correct card.

Active Scope

Filter active card tokens with active() scope.

use PayzeIO\LaravelPayze\Models\PayzeCardToken;

PayzeCardToken::active()->get();

Inactive Scope

Filter inactive card tokens with inactive() scope.

use PayzeIO\LaravelPayze\Models\PayzeCardToken;

PayzeCardToken::inactive()->get();

Log Model

You can access all logs from the database by PayzeIO\LaravelPayze\Models\PayzeLog model.

Get all logs:

use PayzeIO\LaravelPayze\Models\PayzeLog;

PayzeLog::all();

Abandoned Transactions

Abandoned transactions with status Created are automatically reject after about 10 minutes, so you have to run a scheduler to update those transactions' statuses.

If you don't already have a scheduler configured, read how to configure here.

Register our console command in app/Console/Kernel.php's $commands variable:

use PayzeIO\LaravelPayze\Console\Commands\UpdateIncompleteTransactions;

protected $commands = [
    // Other commands
    UpdateIncompleteTransactions::class,
];

Then add a command in a schedule in app/Console/Kernel.php's schedule function. We recommend to run a job every 30 minutes, but it's totally up to you and your application needs.

use PayzeIO\LaravelPayze\Console\Commands\UpdateIncompleteTransactions;

protected function schedule(Schedule $schedule)
{
    // Other commands
    $schedule->command(UpdateIncompleteTransactions::class)->everyThirtyMinutes();
}

Authors

• Levan Lotuashvili
• All Contributors