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

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:

Publish the configuration, migrations and routes:

Run the migrations to create the transaction table:

Configuration

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

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:

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

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

Usage

Starting a payment

Use PayService with PaymentMethodFactory. Pass a payload array:

Or use the setter methods, which are equivalent:

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:

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

Code style is enforced with Laravel Pint:

Support

Having trouble? Work through this list before reaching out:

1. Check the wrapper documentation.
2. Confirm you are on the latest release.
3. Reproduce the issue with BPE_MODE=test and check your Laravel log.
4. 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: [email protected]
• 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 [email protected] 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.}