FAQ
Answers to common questions about the Buckaroo Node SDK.
Something not working? See Troubleshooting.
Getting started
Should I use the SDK or a plugin?
Use a plugin if your store runs on a supported e-commerce platform. It needs no development. See Plugins and apps.
Use the SDK for a custom application or a platform without a Buckaroo plugin.
Does the SDK cost anything?
No. The SDK is free and open source under the MIT license. Transactions are charged according to your Buckaroo contract.
Does the SDK support TypeScript?
Yes. The package includes TypeScript declarations, so service codes, request fields and responses are typed without extra packages.
Does it work with CommonJS and ES modules?
Yes, the package has a build for both. Use the named Buckaroo import or require in either case. See Configuration.
Where do I find my store key and secret key?
In Plaza under Settings → API keys. The store key goes in the websiteKey option. See Configuration.
Can I use the SDK in the browser?
No. The SDK runs on your server only, because it signs requests with your secret key. To collect card data in the browser, use the JS Client Side Encryption SDK or Hosted Fields together with the SDK.
Does the SDK work with Express, NestJS and Next.js?
Yes. The SDK does not depend on a web framework. The push message example uses Express, and only needs the raw request body, which every framework can provide. In Next.js, use it in server code only, such as route handlers. See Push messages.
Payments
Which payment methods can I use?
The Buckaroo payment methods, provided the method is active for your store in Plaza. The example folder has an example for each method, and Payment methods has the details.
Why do field names differ from the API reference?
The API reference describes the raw JSON request and uses PascalCase. The SDK builds that request for you and takes camelCase field names, such as amountDebit. It ignores names it does not recognise. See Payments.
How do I know whether a payment succeeded?
From the push message that Buckaroo sends to your push URL when the status changes. Do not rely on the customer returning to your store. See Push messages.
Can I poll the status instead of handling push messages?
You can look up a transaction with buckaroo.transaction(key).status(), but use that for reconciliation and support. Push messages are faster and are not subject to rate limiting.
Can I issue refunds?
Yes, in full or in part, with the transaction key of the original payment. See Order management.
Why is there no Riverty service code?
Riverty uses the service code afterpay, which was the method's name before it was renamed.
Testing and support
How do I test without real payments?
Create the client with mode: 'TEST'. All requests then go to the Buckaroo test environment. See Test and go live.
Where can I find more examples?
In the example folder of the repository, in JavaScript and TypeScript.
Where do I report a bug or request a feature?
Open an issue in the repository. Pull requests are welcome too. Read the contribution guidelines first.
How do I know when a new version is released?
Watch the releases page on GitHub. The changelog lists what changed in each version.
Updated 30 minutes ago