This package allows you to process payments with Payze.io from your Laravel application.
Please see CHANGELOG for more information what has changed recently.
After upgrading to a newer version, make sure to run publish command to publish the latest migrations. Also, please copy new config file contents to your existing one.
- Installation
- Config
- Payments & Requests
- Payment Request Options
- Controller
- Events
- Relationships
- Models
- Abandoned Transactions
- Authors
composer require payzeio/laravel-payze
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,
],php artisan vendor:publish --provider="PayzeIO\LaravelPayze\PayzeServiceProvider"
And run migrations:
php artisan migrate
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
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.
The general variables are stored in config/payze.php file. More details:
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.
Enable/Disable SSL verification in Guzzle client to avoid SSL problems on some servers. Enabled by default.
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.
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.
The name of the table in the database, which is used to store all the transactions.
The name of the table in the database, which is used to store detailed logs about transactions and API requests.
The name of the table in the database, which is used to store all the saved card tokens.
API key of your Payze.io account.
API secret of your Payze.io account.
All 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 the needed data and then process().
Detailed instructions about needed data and options are in the next section.
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();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();You can pay with a saved card token anytime without customer interaction.
Card tokens can be accessed by PayzeCardToken model or cards relationship. Read more about card tokens model here.
Parameters:
CardToken-PayzeIO\LaravelPayze\Models\PayzeCardToken, requiredAmount-float, optional, default:0
Return: PayzeIO\LaravelPayze\Models\PayzeTransaction
use PayzeIO\LaravelPayze\Requests\PayWithCard;
// Get user's non-expired, default card
$card = $user->cards()->active()->default()->firstOrFail();
return PayWithCard::request($card, 15)
->for($order) // optional
->process();Commit (charge) a blocked (preauthorized) transaction.
Parameters:
TransactionId-string|PayzeIO\LaravelPayze\Models\PayzeTransaction, requiredAmount-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 a refundable transaction.
Parameters:
TransactionId-string|PayzeIO\LaravelPayze\Models\PayzeTransaction, requiredAmount-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();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();Get balance info from the merchant's account.
Return: array
use PayzeIO\LaravelPayze\Requests\GetBalance;
return GetBalance::request()->process();You can pass these parameters to all the payment requests in Payze package.
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();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();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 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.
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();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();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'];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 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
You can add transactions and cards relationships to your models with traits to easily access associated entries.
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.
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.
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();Filter paid transactions with paid() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::paid()->get();Filter unpaid transactions with unpaid() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::unpaid()->get();Filter completed transactions with completed() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::completed()->get();Filter incomplete transactions with incomplete() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::incomplete()->get();Filter refundable transactions with refundable() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::refundable()->get();Filter non-refundable transactions with nonrefundable() scope.
use PayzeIO\LaravelPayze\Models\PayzeTransaction;
PayzeTransaction::nonrefundable()->get();You can access all saved card tokens logged in the database by PayzeIO\LaravelPayze\Models\PayzeCardToken model.
NOTICE: After starting AddCard payment, new database entry is created with non-active token which gets activated after successful payment. So Active card refers to a valid token, which can be used in future payments.
Get all active tokens:
Tokens are automatically filtered by a global scope and only returns active tokens.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
PayzeCardToken::all();Active card tokens have card_mask, cardholder, brand, expiration_date attributes, which can be helpful for a user to choose correct card.
Since tokens are automatically filtered by a global scope, active() scope now returns non-expired card tokens based on expiration date.
Filter active (non-expired) card tokens with active() scope.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
PayzeCardToken::active()->get();Tokens are automatically filtered by a global scope and only returns active tokens. If you want to include inactive card tokens in the list, you should add withInactive() scope to a query:
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
PayzeCardToken::withInactive()->get();Filter inactive card tokens with inactive() scope. This method already includes withInactive() scope, so you don't have to specify it manually.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
PayzeCardToken::inactive()->get();You can check if already fetched PayzeCardToken model instance is expired or not.
Method will return false if expiration date is not filled in database.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
$token = PayzeCardToken::latest()->get();
$token->isExpired();You can check if already fetched PayzeCardToken model instance is expired or not.
Method will return true if expiration date is not filled in database.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
$card = PayzeCardToken::latest()->get();
$card->isActive();You can set current card as a default. All other cards will be unmarked automatically.
use PayzeIO\LaravelPayze\Models\PayzeCardToken;
$card = PayzeCardToken::latest()->get();
$card->markAsDefault();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 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 running 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();
}