Common problems when integrating the Laravel Wrapper, and where to look first.


Buckaroo status

Before you investigate your own code, check whether there is a known incident that affects the platform or a specific payment method.

Buckaroo Status

Loading status…

Work through this first

  1. Check your Laravel log in storage/logs
  2. Confirm that you are on the latest release
  3. Reproduce the issue with BPE_MODE=test
  4. Run php artisan route:list --name=buckaroo to check that the push and return routes exist
  5. Verify that your push URL is reachable from outside your network

Common problems

Buckaroo credentials are missing

The wrapper throws this error when BPE_WEBSITE_KEY or BPE_SECRET_KEY is empty.

  • Check that both variables are in the .env of this environment
  • If you cache your configuration, run php artisan config:cache again. With a cached configuration, changes in .env are not picked up
Authentication fails
  • Confirm that BPE_WEBSITE_KEY holds the store key of the Buckaroo store you mean to use. Each store has its own key
  • Check for a space at the start or end of either key
  • Check BPE_MODE. Without it, the wrapper uses live
Push messages get a 419 response

Laravel's CSRF protection is blocking the push message. Exclude the wrapper's routes from CSRF verification. See Configuration. If you changed the route prefix, exclude the new prefix.

Push messages get a 400 response

The signature did not validate.

  • Check that the keys in this environment belong to the store that sent the push message
  • Behind a proxy or load balancer, configure Laravel's trusted proxies so that the application sees its public URL. The signature of a JSON push message covers the push URL
  • Check that your server passes the Authorization header on to PHP
Push messages get a 500 response

Most often the wrapper could not find the transaction, and the log shows "Transaction not found".

  • The payment was started outside PayService, for example with Buckaroo::api() directly, so it was never stored
  • The push message belongs to another environment that shares the same Buckaroo store, such as a colleague's machine or a staging server
  • The migration has not run in this environment
Payments succeed but my orders stay unpaid
  • Check that the push message arrives: look for requests to the push route in your web server log
  • Check that your listener is registered. On Laravel 9 and 10 it has to be in your EventServiceProvider
  • If your listener is queued, check that a queue worker is running
  • Check that your listener looks at $event->buckarooTransaction->status. The event is also fired for payments that are not paid yet
My order is not updated when the customer cancels

The wrapper does not fire PayTransactionCompleted when the customer cancels the payment. The stored transaction does get the status cancelled. Handle the cancellation on your return page, or check the transaction status when the customer comes back to the order.

The customer sees JSON after paying

That is the default response of the wrapper's return route. Define your own return route to show a page. See The return page.

Route [buckaroo.return] not defined

The wrapper builds the return and push URLs from the routes named buckaroo.return and buckaroo.push. If you set BPE_LOAD_ROUTES=false, define both routes yourself with exactly those names.

A field I send does not reach Buckaroo

The PHP SDK silently ignores field names it does not recognise. Write them in camelCase, such as amountDebit and originalTransactionKey.

A payment method is rejected that should work

Check that the method is active for your store in Plaza, and that the fields match what the method expects. See Payment methods.

For problems in the payment request itself, see Troubleshooting in the PHP SDK documentation.


Contact support

Still stuck? Tell us what you expected to happen and what happened instead, and add whatever applies:

  • Your PHP version, Laravel version and package version
  • The service and action you called
  • The Buckaroo transaction key, if a transaction exists
  • The relevant lines from your Laravel log
  • Whether you were in test or live mode

Never share your secret key, with us or with anyone else. Support never needs it. Remove it from any logs you send.

For bugs and feature requests, open an issue. Report a security issue privately to support, not in a public issue. Our contact details are on the Contact us page.



Did this page help you?