Configuration
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=testBoth keys are in Plaza under Settings → API keys.
| Key | What it is |
|---|---|
| Store key | Identifies the Buckaroo store that the transaction belongs to. Each store has its own key |
| Secret key | Signs your requests and verifies push messages. It belongs to your Buckaroo account |
BPE_WEBSITE_KEYtakes 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
.envfile.
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_MODEis not set, the wrapper useslive. SetBPE_MODE=testin 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.
| Variable | Config key | Purpose | Default |
|---|---|---|---|
BPE_WEBSITE_KEY | website_key | Your store key | None |
BPE_SECRET_KEY | secret_key | Your secret key | None |
BPE_MODE | mode | test or live | live |
BPE_TRANSACTION_MODEL | transaction_model | The model that stores transactions | BuckarooTransaction |
BPE_LOAD_ROUTES | routes.load | Whether the wrapper registers its routes | true |
BPE_ROUTE_PATH | routes.prefix | The path prefix of the routes | buckaroo |
Routes
The wrapper registers two routes:
| Route | Name | Used for |
|---|---|---|
POST /buckaroo/push | buckaroo.push | Push messages from Buckaroo |
GET and POST /buckaroo/return | buckaroo.return | The 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.
Updated about 7 hours ago