Troubleshooting

Common problems when integrating the Python SDK, and where to look first.


Buckaroo status

Before you investigate your own code, check whether there is a known incident that affects the platform or a specific payment method.

Buckaroo Status

Loading status…

Work through this first

  1. Check the API reference for the service and action you are calling
  2. Confirm that you are on the latest release
  3. Reproduce the issue with mode="test" and inspect response.get_some_error(), the status code and response.to_dict()
  4. Verify that your push URL is reachable from outside your network

Common problems

Authentication fails

The SDK raises an AuthenticationError when the keys are missing or rejected.

  • Confirm that the store key belongs to the Buckaroo store you mean to use. Each store has its own key
  • Check the mode. With Buckaroo.from_env(), it comes from BUCKAROO_MODE
  • Check that the environment variables are set in the process. The SDK does not load a .env file for you
  • Call client.confirm_credential() to test the keys on their own. See Configuration
The SDK reports missing required fields

Every request needs currency, amount, invoice, description and the four return URLs, including refunds and captures. One missing field raises a ParameterValidationError, several raise a ValueError that lists them. See Payments.

A field I send does not reach Buckaroo

The SDK silently ignores fields it does not recognise.

  • Top-level fields use snake_case, such as return_url and push_url
  • Fields that belong to the payment method go in service_parameters
  • The card brand is a top-level brand field, not a service parameter
The request is rejected for a duplicate invoice number

Every payment needs a unique invoice number. Generate it from your own order numbering, not from a counter that can reset.

A payment is declined but no exception is raised

That is by design. A payment that Buckaroo receives and declines is a normal response. Check is_failed(), is_cancelled() and the status code, and read get_some_error() for the reason. Exceptions are only raised when the request itself does not complete. See Payments.

Payments succeed but my orders stay unpaid

The push message is not reaching you, or your handler rejects it.

  • Check that the push URL is reachable from the internet and is not behind basic authentication or a login
  • Check that Buckaroo's push IP addresses and ports are allowed through your firewall. See Push messages
  • Check that push messages are enabled in the push settings of your store in Plaza, or that you send a push_url with each request
  • Check that your handler returns HTTP 200, and that your framework's CSRF protection does not block the request
Push validation fails on a genuine push message

validate() returns False when the signature does not match.

  • Pass the raw request body, not a body that was parsed and serialised again
  • Pass the push URL that Buckaroo called. Behind a proxy or load balancer, the host or path your application sees can differ from the public one
  • Check that your server passes the Authorization header on to your application
  • Check that the verifier uses the same store key and secret key as the store that sent the push message
Orders are processed twice

The same push message can arrive more than once. Check whether you have already handled that transaction key and status before you act on it. See Push messages.

A payment method is rejected that should work

Check that the method is active for your store in Plaza, and that the fields match what the method expects. Requirements differ: some methods need address and article details, and some have amount or country limits. See Payment methods.

The request times out

The SDK raises a BuckarooApiError when Buckaroo cannot be reached. Buckaroo may still have processed the payment, so wait for the push message before you retry. You can set the timeout in the client configuration.


Contact support

Still stuck? Tell us what you expected to happen and what happened instead, and add whatever applies:

  • Your Python version and SDK version
  • The service and action you called
  • The Buckaroo transaction key, if a transaction exists
  • The error message, including the status subcode
  • Whether you were in test or live mode

Never share your secret key, with us or with anyone else. Support never needs it. Remove it from any logs you send.

For bugs and feature requests, open an issue. Report a security issue privately to support, not in a public issue. Our contact details are on the Contact us page.


Did this page help you?