README

Buckaroo for Laravel

About · Requirements · Installation · Configuration · Usage · Testing · Support · Contribute

About

This package integrates the Buckaroo payment gateway into a Laravel application. It wraps the Buckaroo PHP SDK in Laravel conventions: a service provider, a facade, publishable config, migrations and routes for the return and push callbacks.

Use it to start payments and to handle refunds, captures and authorization cancellations. Every part is designed to be overridden, so you can swap the transaction model or define your own routes without forking the package.

If you run a shop on a supported e-commerce platform, use the ready-made plugin for Magento 2, Shopware 6, WooCommerce or Odoo instead. This package is for custom Laravel applications.

Full wrapper documentation on docs.buckaroo.io. For request parameters and service codes, see the API reference.

Requirements

Requirement	Supported versions
PHP	8.0 or higher
Laravel	9, 10, 11, 12 and 13
Buckaroo PHP SDK	1.10 or higher (installed automatically)

You also need a Buckaroo account and an up-to-date SSL/TLS toolkit such as OpenSSL. Don't have an account yet? Request an account.

Installation

Install the package with Composer:

composer require buckaroo/laravel

Publish the configuration, migrations and routes:

php artisan vendor:publish --provider="Buckaroo\Laravel\BuckarooServiceProvider"

Run the migrations to create the transaction table:

php artisan migrate

Configuration

Add your credentials to .env. You can find both keys under API credentials in Buckaroo Plaza.

BPE_WEBSITE_KEY=your_store_key
BPE_SECRET_KEY=your_secret_key
BPE_MODE=test

Set BPE_MODE to test while developing and to live in production. The client is initialised automatically during the application boot, so no further wiring is needed.

Note

The Store key was previously called the Website key. The environment variable is still named BPE_WEBSITE_KEY for backwards compatibility.

Excluding the push route from CSRF verification

Buckaroo cannot send a CSRF token with its push messages, so the package's routes must be excluded from CSRF verification.

On Laravel 11 and higher, add this to bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'buckaroo/*',
    ]);
})

On Laravel 9 and 10, add the path to the $except array in app/Http/Middleware/VerifyCsrfToken.php:

protected $except = [
    'buckaroo/*',
];

If you changed the route prefix, use that prefix instead of buckaroo.

Overriding the transaction model

The package stores transactions using Buckaroo\Laravel\Models\BuckarooTransaction. Point config/buckaroo.php at your own model to extend it:

'transaction_model' => YourCustomTransactionModel::class,

Customising the routes

The package registers routes for the return and push callbacks. Change the prefix, or turn them off and define your own, in config/buckaroo.php:

'routes' => [
    'load' => env('BPE_LOAD_ROUTES', true),
    'prefix' => env('BPE_ROUTE_PATH', 'buckaroo'),
],

Initialising the client manually

use Buckaroo\Laravel\Facades\Buckaroo;
use Buckaroo\Transaction\Config\DefaultConfig;

Buckaroo::api()->setBuckarooClient(
    new DefaultConfig(
        websiteKey: config('buckaroo.website_key'),
        secretKey: config('buckaroo.secret_key'),
        mode: config('buckaroo.mode'),
        returnURL: route('buckaroo.return'),
        pushURL: route('buckaroo.push'),
    )
);

Usage

Starting a payment

Use PayService with PaymentMethodFactory. Pass a payload array:

use Buckaroo\Laravel\Api\PayService;
use Buckaroo\Laravel\Handlers\PaymentMethodFactory;

$paymentSessionService = PayService::make(
    PaymentMethodFactory::make('noservice')->setPayload([
        'currency' => 'EUR',
        'amountDebit' => 100,
        'order' => '000-ORD',
        'invoice' => '000-INV',
        'description' => 'This is a description',
        'continueOnIncomplete' => '1',
        'servicesSelectableByClient' => 'ideal,bancontactmrcash',
    ])
);

Or use the setter methods, which are equivalent:

$paymentSessionService = PayService::make(
    PaymentMethodFactory::make('noservice')
        ->setCurrency('EUR')
        ->setAmountDebit(100)
        ->setOrder('000-ORD')
        ->setInvoice('000-INV')
        ->setDescription('This is a description')
        ->setContinueOnIncomplete('1')
        ->setServicesSelectableByClient('ideal,bancontactmrcash')
);

Passing noservice lets the customer pick a method from servicesSelectableByClient. Pass a service code such as ideal to start a payment with one specific method.

Calling the API directly

For full control, address the wrapper directly:

use Buckaroo\Laravel\Facades\Buckaroo;

$response = Buckaroo::api()->method('ideal')->pay([
    'currency' => 'EUR',
    'amountDebit' => 100,
    'order' => '000-ORD',
    'invoice' => '000-INV',
    'description' => 'Payment for Order 000-ORD',
]);

Replace ideal with any service code, and pay with the action you need, such as refund. Service codes for every payment method are listed in the API reference.

Other services

RefundService, CaptureService and CancelAuthorizeService follow the same pattern as PayService.

Testing

composer install
./vendor/bin/phpunit

Code style is enforced with Laravel Pint:

./vendor/bin/pint

Support

Having trouble? Work through this list before reaching out:

Check the wrapper documentation.
Confirm you are on the latest release.
Reproduce the issue with BPE_MODE=test and check your Laravel log.
Verify that your push URL is reachable from outside your network. Buckaroo sends push messages from fixed IP addresses and ports, so make sure these are on your allow list. See push messages for the current list.

Still stuck? Contact us and include your PHP version, Laravel version, package version, the relevant log lines and the transaction key.

Bug reports and feature requests: open an issue
Technical support: support@buckaroo.nl
Phone: +31 (0)30 711 50 50
Gateway status: status.buckaroo.io

Contribute

We really appreciate it when developers help improve the Buckaroo wrappers. Please read our Contribution Guidelines before opening a pull request, and target the main branch.

Found a security issue? Please report it privately to support@buckaroo.nl instead of opening a public issue.

Versioning

We follow semantic versioning (MAJOR.MINOR.PATCH):

MAJOR — breaking changes that require additional testing and caution.
MINOR — new functionality with limited impact.
PATCH — bug fixes and hotfixes only.

All changes are documented on the releases page.

License

This package is open source software licensed under the MIT license.

_{Made with care by Buckaroo.

This document is subject to change; typos and language errors are possible.}

buckaroo / laravel

Maintainers

Package info

Statistics

Security