The wrapper reads its settings from .env and creates the Buckaroo client when your application boots. After you add your keys and exclude the push route from CSRF verification, it is ready to use.


Add your credentials

BPE_WEBSITE_KEY=your_store_key
BPE_SECRET_KEY=your_secret_key
BPE_MODE=test

Both keys are in Plaza under Settings → API keys.

KeyWhat it is
Store keyIdentifies the Buckaroo store that the transaction belongs to. Each store has its own key
Secret keySigns your requests and verifies push messages. It belongs to your Buckaroo account

BPE_WEBSITE_KEY takes your store key. The store key used to be called the website key, and the variable kept its name.

Keep your secret key out of version control. Anyone who has it can sign requests in your name. Do not commit your .env file.


Test and live mode

BPE_MODE decides which Buckaroo environment receives your requests: test or live. In test mode, no real money is moved.

If BPE_MODE is not set, the wrapper uses live. Set BPE_MODE=test in every environment that is not production.


Exclude the push route from CSRF verification

Buckaroo cannot send a CSRF token with a push message, so Laravel rejects it unless you exclude the wrapper's routes.

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 app/Http/Middleware/VerifyCsrfToken.php:

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

If you change the route prefix, use that prefix here in place of buckaroo.


All settings

php artisan buckaroo:publish places the configuration file in config/buckaroo.php.

VariableConfig keyPurposeDefault
BPE_WEBSITE_KEYwebsite_keyYour store keyNone
BPE_SECRET_KEYsecret_keyYour secret keyNone
BPE_MODEmodetest or livelive
BPE_TRANSACTION_MODELtransaction_modelThe model that stores transactionsBuckarooTransaction
BPE_LOAD_ROUTESroutes.loadWhether the wrapper registers its routestrue
BPE_ROUTE_PATHroutes.prefixThe path prefix of the routesbuckaroo

Routes

The wrapper registers two routes:

RouteNameUsed for
POST /buckaroo/pushbuckaroo.pushPush messages from Buckaroo
GET and POST /buckaroo/returnbuckaroo.returnThe customer returning after payment

Every payment you start through the wrapper uses these as its push URL and return URL, unless you pass your own pushURL or returnURL.

To change the path, set BPE_ROUTE_PATH. To define the routes yourself, set BPE_LOAD_ROUTES=false and add your own routes with the same names. See Push messages and events.


Use your own transaction model

The wrapper stores transactions with Buckaroo\Laravel\Models\BuckarooTransaction. To add relations or behaviour, extend that model and point the configuration at your class:

namespace App\Models;

use Buckaroo\Laravel\Models\BuckarooTransaction;

class PaymentTransaction extends BuckarooTransaction
{
    protected $table = 'buckaroo_transactions';

    public function shopOrder()
    {
        return $this->belongsTo(Order::class, 'order', 'number');
    }
}
// config/buckaroo.php
'transaction_model' => App\Models\PaymentTransaction::class,

Set up the client yourself

To use different credentials at runtime, for example in an application with more than one store, set the client yourself:

use Buckaroo\Laravel\Facades\Buckaroo;

Buckaroo::api()->setBuckarooClient($storeKey, $secretKey, 'test');

setBuckarooClient() also accepts a configuration object from the PHP SDK in place of the three values. See Configuration in the PHP SDK documentation.


Did this page help you?