Connect your account
Link your Magento store to Buckaroo with your API keys, and make sure your server can receive push messages.
Get your API keys
You need two values from Buckaroo Plaza → Settings → API Keys:
| Key | Scope | Notes |
|---|---|---|
| Store key | One per website in your Buckaroo account | Previously called the Merchant key. Use a separate Store key per store view if you want transactions reported separately per shop. |
| Secret key | One for your entire Buckaroo account | Used to sign requests and to verify incoming push messages. Treat it like a password. |
Never commit your Secret key to version control or share it in a support ticket. If it leaks, regenerate it in Plaza. Note that regenerating invalidates the old key immediately for every store using it.
Enter the keys in Magento
- Log in to the Magento admin.
- Go to Stores → Configuration → Sales → Buckaroo.
- Open the Credentials section.
- Set Enabled to
Yes. - Paste your Store key and Secret key.
- Select Save Config.
Test mode and live mode
The Buckaroo plugin doesn't have a single global test switch. Mode is set per payment method: each method can be Off, Test or Live. This lets you go live with Wero while still testing Klarna, but it also means you must check every enabled method before launch.
Test and go live has the full checklist.
Test and live transactions use the same Store key and Secret key. The only thing separating them is the per-method mode setting. Before going live, confirm that no method is still set to
Test.
Multi-store configuration
Configuration scope works the same way as any other Magento setting. Switch the Store View selector at the top left of the configuration page, clear Use Website on the fields you want to override, and enter a different Store key.
Typical setup for a merchant running example.nl and example.be:
- Secret key at default scope, shared across the account.
- Store key at website scope, one Buckaroo website per storefront.
- Payment method availability at store view scope: Bancontact enabled for BE only, Wero for NL only.
Push messages
A push message is Buckaroo's server-to-server notification that a payment has reached a final status. Your store uses it to update the order. The customer's browser may never come back: they close the tab, their connection drops, or the method settles hours later. That makes the push the authoritative source, not the redirect.
You don't need to configure a push URL. The plugin sends the correct push URL with every transaction request, which overrides whatever is configured in Plaza for that website. There's nothing to set up in Plaza or in the Magento admin.
What you do need is a server that will accept the incoming request.
Allow Buckaroo's IP addresses and ports
If your store sits behind a firewall, WAF, or IP allowlist, push messages will be blocked and your orders will never leave "Pending payment".
Allow inbound traffic from Buckaroo's push addresses on the supported ports. The current list is maintained on the Push messages page. Always take the values from there rather than from a copy, since they can change.
This allowlist is for traffic from Buckaroo to your store. Don't confuse it with traffic in the other direction. The addresses your store sends requests to are dynamic and should not be allowlisted by IP.
Other things that block pushes
Your push endpoint must also be:
- Publicly reachable over HTTPS with a valid certificate. Self-signed certificates will fail.
- Not behind basic authentication. Staging environments protected with HTTP auth will reject pushes.
- Not cached. Exclude the plugin's routes from Varnish and any CDN. See Installation.
- Returning HTTP 200. Buckaroo treats any other status code as a failed push.
Retries
If a push fails, Buckaroo retries automatically over a period of hours, and keeps trying for up to three days before giving up. See Push messages for the exact schedule.
What this means in practice: a firewall rule fixed the same day will usually let orders reconcile themselves without any manual work. It's a generous window, but not unlimited, so don't leave a broken endpoint over a long weekend.
Plaza can optionally email you when pushes fail, under Settings → Websites → Push settings → E-mail push failure. Bear in mind it warns on the first failed attempt, so a push that fails once and succeeds on retry still triggers an email. On a busy store that adds up, so it suits a launch period or an active investigation better than permanent use.
Test the connection
Place a test order using Wero in test mode and choose the "success" outcome on the test page. Within a few seconds the order in Magento should move out of pending. If it doesn't:
- Check the Logs tab in Buckaroo Plaza for the transaction. It shows every push attempt and any error returned by your server, which usually identifies the problem immediately.
- Enable debug logging under Stores → Configuration → Sales → Buckaroo → Advanced → Debug and place another test order.
- Look for the push in
var/log/Buckaroo/, where there is one file per day.
If Plaza shows the push failing with a connection error or timeout, it's a firewall or network problem. If Plaza shows the push succeeding but Magento didn't act on it, it's a signature or configuration problem, most often a Secret key mismatch. See Troubleshooting.
You can resend a push manually from Plaza: open the transaction and use Actions. To resend many at once, use Transactions → Overview → Filters → Actions → Bulk Push. This is how you recover a batch of orders after fixing a blocked firewall.
Updated 6 minutes ago