Troubleshooting

By far the most common issue. The payment succeeded at Buckaroo but the push message never reached Odoo, or was rejected.

Start in Plaza, not Odoo. Open the transaction and look at the Logs tab. It shows every push attempt and the response your server gave, which tells you straight away which half of the connection failed.

If Plaza shows no push attempts at all, pushes aren't being sent for that store. Check that push messages are enabled in Plaza under Settings → Stores → Push settings, for the store whose Store key is in Odoo.

If the pushes failed with a timeout or connection error, the request never reached your store:

1. Are Buckaroo's IPs allowlisted? A firewall, WAF or hosting-level IP allowlist blocking them is the single most common cause. Check the current list against your rules. If the allowlist was set up a while ago, an address may have been added since.
2. Are the required ports open for inbound traffic from those addresses?
3. Is the store behind basic auth? Common on staging. Buckaroo can't authenticate.
4. Is https://your-odoo-domain/payment/buckaroo_official/webhook reachable from outside your network?

If Plaza shows the pushes being delivered successfully but Odoo didn't act on them:

5. Do the Secret keys match? If the key in Odoo differs from the one in Plaza, the signature check fails and the push is discarded. This often happens after a key is regenerated in one place but not the other.
6. Check the Odoo server log. A rejected push is logged.

You don't need to check the push URL itself. The app sends it with every transaction request, so it can't be misconfigured. What can be wrong is whether pushes are enabled for the store at all.

Once you've fixed the cause, you don't have to chase the affected orders manually. Buckaroo retries for three days, so recent orders may resolve themselves. For older ones, resend from Plaza: open the transaction and use Actions, or use Transactions → Overview → Filters → Actions → Bulk Push to resend a batch.

Bank Transfer and PayPerEmail are pending by design until the customer actually pays. Don't chase those as failures.

The app needs the buckaroo-sdk Python package. If it isn't available to the Python environment running Odoo, the app can't load.

• Self-hosted: run pip install -r requirements.txt from the app folder, using the same Python environment as Odoo, then restart the service.
• Odoo.sh: add the contents of the app's requirements.txt to your project's own requirements.txt and rebuild.

Go to Apps and select Update Apps List first. Odoo only picks up new folders in the addons path after that.

If it still doesn't appear, confirm the payment_buckaroo_official folder sits directly in a folder on your addons path, and that Odoo has been restarted.

If you see Buckaroo but not Buckaroo Official, that's Odoo's own built-in provider. The official app is not installed yet.

Usually credentials.

• Confirm the Store Key and Secret Key have no leading or trailing whitespace. Copy-paste from Plaza often picks up a trailing space.
• The Secret key applies to your whole account, the Store key is per store. Mixing up two stores' keys produces the same error.
• Confirm the provider is not set to Disabled.
• If the keys are definitely right, check whether outbound HTTPS from your Odoo server to Buckaroo is blocked.

Work down this list:

1. Is the method added to the Buckaroo Official provider and active?
2. Is the method active on your Buckaroo contract? Check Plaza.
3. Does the order total fall within the method's minimum and maximum amount?
4. Does the currency and the customer's country match what the method supports?
5. For Apple Pay, Google Pay and PayPal, is Show on Checkout enabled?
6. For Apple Pay: is your domain verified, and are you on a supported browser and device?

• Apple Pay only shows in Safari on a supported Apple device with a card in Wallet. It will not appear in Chrome on Windows.
• In inline mode, open /.well-known/apple-developer-merchantid-domain-association on your store. A 404 means Apple can't verify your domain.
• Check that the Buckaroo Merchant GUID is filled in.
• If you can't get domain verification working, switch Integration Mode to Redirect as an interim step.

Fill in the Google Merchant ID from the Google Pay & Wallet Console. It isn't needed for test sessions but is required in production.

Test mode uses the PayPal Sandbox Merchant ID, and the sandbox order has to be approved under that same sandbox merchant. Check that the sandbox value is filled in and that you're signing in with the matching sandbox buyer account.

• Check the value on the method: a fixed amount like 1.50, or a percentage like 1%. Empty or 0 means no fee.
• The percentage is calculated over the order subtotal excluding delivery, so a very small order can round to zero.
• The fee line is added when the customer selects the method, not when the cart is created.

Klarna, In3, Billink and Riverty need extra customer details, and the app raises an error rather than sending an incomplete request. Check that the customer's date of birth, gender or salutation is filled in on the contact, under Sales & Purchase.

These methods also send order lines, so the payment has to come from a sale order with at least one line.

• Is the credit note posted, rather than a draft?
• Is the credit note linked to a Buckaroo payment that is done?
• Does that payment still have an amount available to refund?
• If the credit note covers more than one Buckaroo payment, refund each payment record individually instead.
• For Riverty, refunds from Odoo must be for the full amount. Use Plaza for a partial Riverty refund.
• Has the order already been refunded in Plaza? A double refund will be rejected.

Plaza refunds reach Odoo through a push message and are recorded as a separate refund transaction on the original payment. If it hasn't appeared, the push isn't arriving. See the pending-transaction entry above.

Decline reasons come from the issuing bank, not from Buckaroo or Odoo. The specific code is visible in Plaza under the transaction. See Decline codes for what each one means. "Do Not Honor" in particular is more nuanced than it sounds.

1. Check the changelog for the versions you moved through. A breaking change may be documented.
2. Re-run the app upgrade and restart the Odoo service.
3. Confirm buckaroo-sdk is still installed and at the version the app expects.
4. Confirm your Odoo version is still supported by the app version you're on.