Troubleshooting

Common problems when integrating the Node 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.data, including the status subcode and message
  4. Verify that your push URL is reachable from outside your network

Common problems

Buckaroo.InitializeClient is not a function

Use the named import: import { Buckaroo } from '@buckaroo/buckaroo_sdk', or const { Buckaroo } = require('@buckaroo/buckaroo_sdk') with CommonJS. In a native Node.js ES module, the default import does not give you the client class.

Authentication fails

The SDK throws 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, and it goes in the websiteKey option
  • Check that your environment variables are set in the process. The SDK does not read them or load a .env file for you
  • Check the mode
  • Call confirmCredentials() to test the keys on their own. See Configuration
Invalid payment method code

The SDK throws a ParameterValidationError for a service code it does not know. Service codes are lowercase, such as ideal and visa. Bancontact is bancontactmrcash and Riverty is afterpay.

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.

Nothing happens when I call pay()

pay() and the other actions only build the request. Call .request() to send it, and await the result.

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 error is thrown

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

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

  • Pass the raw request body as a string. If a body parser such as express.json() or express.urlencoded() runs first, the body is an object and the original string is lost
  • Check that the client uses the same store key and secret key as the store that sent the push message
  • For the JSON format, also pass 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
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 throws a BuckarooApiError 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. The default timeout is 10 seconds, and you can change it with the timeout option. See Configuration.


Contact support

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

  • Your Node.js 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?