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.
Work through this first
- Check the API reference for the service and action you are calling
- Confirm that you are on the latest release
- Reproduce the issue with
mode="test"and inspectresponse.get_some_error(), the status code andresponse.to_dict() - 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 fromBUCKAROO_MODE - Check that the environment variables are set in the process. The SDK does not load a
.envfile 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_urlandpush_url - Fields that belong to the payment method go in
service_parameters - The card brand is a top-level
brandfield, 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_urlwith 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
Authorizationheader 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.
Updated about 2 hours ago