Troubleshooting

Common problems when integrating the PHP 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 in test mode with a logger attached, and inspect the response, including the status subcode and message
  4. Verify that your push URL is reachable from outside your network

Common problems

Authentication fails

The SDK throws an AuthenticationException 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 for a leading or trailing space in either key, which is easy to add when you copy it from Plaza
  • Check the mode, and whether BPE_MODE is set in your environment. It overrides the mode you pass to the client
  • Call confirmCredential() to test the keys on their own. See Configuration
A field I send does not reach Buckaroo

The SDK silently ignores field names it does not recognise. Write them in camelCase, such as amountDebit and originalTransactionKey, not in the PascalCase that the API reference shows. Also check the spelling against the example for that method in the repository.

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 thrown

That is by design. A payment that Buckaroo receives and declines is a normal response. Check isSuccess(), isFailed() and isRejected(), and read getSomeError() for the reason. Exceptions are only thrown 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 pushURL with each request
  • Check that your handler returns HTTP 200
Push validation fails on a genuine push message

isValid() returns false when the signature does not match.

  • For the JSON format, pass the raw request body, the Authorization header and 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
  • Some server setups do not pass the Authorization header to PHP. Check that $_SERVER['HTTP_AUTHORIZATION'] is filled
  • Check that the client uses the same store key and secret key as the store that sent the push message
  • For the HTTP POST format, pass the unmodified $_POST array
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.

Card data is rejected in the encrypted flow

The encrypted string has to come from the JS Client Side Encryption SDK and is passed in the encryptedCardData field. Other field names are ignored.

The request times out

The SDK throws a TransferException when Buckaroo cannot be reached. Buckaroo may still have processed the payment, so wait for the push message or look up the transaction before you retry. You can set the timeouts in the client configuration.


Contact support

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

  • Your PHP 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 questions about the SDK, start a discussion. 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?