Configure the Buckaroo Magento 2 plugin

Configure how the plugin behaves across your store: transaction labels, invoicing, payment fees and refunds.

All settings live under Stores → Configuration → Sales → Buckaroo in the Magento admin. Every setting can be scoped to default, website or store view.

📘
If you haven't added your API keys yet, start with Connect your Buckaroo account.

General settings

Settings are split across two sections at the top of the page.

API Keys

Setting	What it does
Enabled	Turns the whole plugin on or off. Off by default. Disabling hides all Buckaroo payment methods from checkout.
Store Key	Your Store key from Buckaroo Plaza. There is one per website in your Buckaroo account.
Secret Key	Your Secret key from Buckaroo Plaza. There is one per account, and it also verifies incoming push messages.

General Settings

Setting	What it does
Transaction Label	The description your customer sees on their bank statement.
Invoice Handling	When Magento creates the invoice: on successful payment, or on shipment.
Buckaroo Payment Fee Tax Class	The tax class applied to payment fees, if you charge any.

Transaction label

Set a description your customers will recognise on their bank statement. Unrecognised descriptions are a common cause of chargebacks, so use something that clearly identifies your shop.

You can use these tags:

{order_number}   →  10000
{shop_name}      →  Storename

The default is Order {order_number}. Adding your shop name is usually worth it. {shop_name} {order_number} renders as Storename 10000, which a customer is far more likely to recognise on a statement than an order number alone.

📘
There's a separate Refund Label under the Refunding section, with the same tags. It defaults to Order {order_number} too, but you may want to make refunds visibly distinct on a statement.

Invoice handling

Choose when Magento generates the invoice:

On successful payment: the invoice is created as soon as Buckaroo confirms the payment. Best for most shops.
On shipment: the invoice is created when you ship. Use this if your accounting process requires the invoice to reflect what actually left the warehouse, or if you frequently ship partial orders.

For authorise-and-capture methods, the invoice is what triggers the capture. There is more on this in Order management.

Payment fees

You can charge a fee per payment method. Fees are configured per method on the Payment methods page; the Buckaroo Payment Fee Tax Class here determines how that fee is taxed.

Refunds

Open the Refunding tab.

Setting	What it does
Enabled	Whether refunds created in Magento are sent to Buckaroo.
Push Buckaroo Plaza Refunds to Magento	Whether refunds initiated in Buckaroo Plaza are reflected back in Magento as credit memos.
Refund Label	Statement description for refunds. Defaults to `Order {order_number}` and supports the same tags as the transaction label.
Create Refund on Approve for Pending Approval Refunds	For accounts where refunds need signing off in Buckaroo Plaza by an employee with approval rights. Creates the Magento credit memo when the refund is approved, rather than when it's submitted.

⚠️
Both refund options are off by default. If you've never touched this section, refunds you create in Magento are not reaching Buckaroo. You'll need to process them manually in Buckaroo Plaza instead.

Recommended setup

Use Magento as your main system and refund only from there: set Enabled to Yes and create a credit memo for every refund. Magento stays the single source of truth, stock is returned automatically, and your books match.

⚠️
Don't refund the same order in both systems. If a refund is triggered from Magento and from Buckaroo Plaza, you can end up with a duplicate refund or a second credit memo for the same amount.

Refunding from Plaza instead

Occasionally you'll need to refund in Plaza rather than Magento. When that happens, record it in Magento with an offline credit memo. That keeps your administration and stock correct without sending a second refund to Buckaroo.

Push Buckaroo Plaza Refunds to Magento exists for shops that routinely refund from Plaza and want Magento to create those credit memos automatically. If Magento is your main system, leave it off.

Advanced settings

❗️
These settings are for advanced users. Changing the defaults can disrupt order workflows and degrade the reliability of Buckaroo payment methods. Change them at your own risk, and test on staging first.

The Advanced section contains four groups.

Adjust Default Order Statuses

Setting	Default
New Status	`pending`
Pending Payment Status	`pending_payment`
Payment Success Status	`processing`
Payment Failed Status	`canceled`
'Canceled' State on Failed Payment	Yes
Cancel Order on Browser Back Button	No

Order management explains what these mean in practice.

Redirect After Payment Attempt

Setting	Default
Redirect Url After 'Success'	`checkout/onepage/success`
Redirect to Checkout Payment Section After 'Failure'	No
Redirect Url After 'Failure'	`checkout/cart`

Email Settings

Setting	Default
Send Order Confirmation Email	Yes
Send Order Confirmation Email in Sync Mode	No
Send Transactional Invoice Email	Yes

Miscellaneous

Setting	What it does	Default
Create Order Before Transaction	Whether the Magento order is created before the payment is attempted.	Yes
Client IP Detection Headers	Which headers to read the customer's IP from. Set this if you're behind a proxy, CDN or load balancer. Otherwise every transaction reports your proxy's IP, which weakens fraud checks.
Add Customer Data to Request	Sends additional customer details with the transaction.
Keep Cart Alive	Restores the cart if the customer uses the browser back button instead of paying.	Yes
Advanced Order Export for Giftcards	Extended export data for giftcard orders.

Logging

A separate Logging section controls how much the plugin records.

Setting	What it does	Default
Log Level	Minimum severity to record, from Debug through Emergency.
Log Handler	Where logs go: File, Database, or both.	Both
Debug Backtrace Logging Depth	How many stack frames to record.	10
Log Retention Period	How long logs are kept: Day, Week, Month or Year.	Week

Troubleshooting covers how to read them.

Next steps

Payment methods

Enable and configure individual methods.

Order management

Statuses, invoices, refunds and captures.

Test and go live

Verify everything before launch.