Buckaroo Node SDK

About · Requirements · Installation · Getting started · Server-side use only · Testing · Support · Contribute

About

Buckaroo is a Dutch Payment Service Provider. More than 54,000 organisations rely on the Buckaroo platform to process their payments, subscriptions and unpaid invoices.

This is Buckaroo's official Node SDK: a modern, open source library that connects a JavaScript or TypeScript application to the Buckaroo API. It ships CommonJS and ES module builds along with TypeScript declarations, so it works in either module system without extra configuration.

Full SDK documentation on docs.buckaroo.io, and the API reference for request parameters and service codes.

Requirements

You also need a Buckaroo account. Don't have one yet? Request an account.

Installation

npm install @buckaroo/buckaroo_sdk

Or with yarn:

yarn add @buckaroo/buckaroo_sdk

Getting started

Configuring the client

You can find your Store key and Secret key under API credentials in Buckaroo Plaza. Set mode to TEST while developing and to LIVE in production.

import Buckaroo from '@buckaroo/buckaroo_sdk';

const buckarooClient = Buckaroo.InitializeClient(
    {
        websiteKey: 'YOUR_STORE_KEY',
        secretKey: 'YOUR_SECRET_KEY',
    },
    {
        mode: 'TEST', // or 'LIVE'
        currency: 'EUR',
        returnURL: 'https://example.com/return',
        pushURL: 'https://example.com/push',
    }
);

[!NOTE] The websiteKey option takes your Store key. The Store key was previously called the Website key, and the option name has been kept for backwards compatibility.

[!TIP] Keep your Secret key out of version control. Load both keys from environment variables instead — the repository ships an .env.example to start from.

Creating a payment

Every payment method takes a slightly different payload. This example charges a Mastercard:

const payment = await buckarooClient
    .method('mastercard')
    .pay({
        amountDebit: 100,
    })
    .request();

Swap mastercard for any other service code to use a different payment method. Service codes and their parameters are listed in the API reference.

Retrieving transaction information

Once a transaction exists you can query it on demand:

const transaction = buckarooClient.transaction(payment.getTransactionKey());

await transaction.status();     // transaction status
await transaction.refundInfo(); // refund info
await transaction.cancelInfo(); // cancellation info

Validating push messages

Pass the raw request body to ReplyHandler as a string. Read the push values from data(), not from your own parse of the body. data() only returns the fields after they pass validation.

import { ReplyHandler } from '@buckaroo/buckaroo_sdk';

// HTTP post push: the raw application/x-www-form-urlencoded body
const reply = new ReplyHandler(buckarooClient.credentials, rawBody).validate();

// JSON push: also pass the Authorization header and the full push URL
// const reply = new ReplyHandler(buckarooClient.credentials, rawBody, req.headers.authorization, pushUrl).validate();

if (reply.isValid()) {
    const push = reply.data();
    // push.brq_statuscode, push.brq_invoicenumber, ...
}

More runnable examples are in example/.

Server-side use only

[!WARNING] Use this library from your server only. Never bundle it into a website or mobile app.

This library is written in JavaScript, so it is technically possible to include it in front-end code — but doing so exposes your Secret key to everyone who loads the page. Anyone holding that key can act on your account's behalf.

In the intended setup, your server holds the Secret key and calls the Buckaroo API through this SDK. Nothing sensitive reaches the browser.

Testing

npm install
npm test

Tests run with Jest. Formatting is handled by Prettier:

npm run prettier

Tests that talk to the Buckaroo test environment need credentials, so copy .env.example to .env and fill in your test Store key and Secret key first.

Support

Having trouble? Work through this list before reaching out:

1. Check the SDK documentation and the API reference.
2. Confirm you are on the latest release.
3. Reproduce the issue with mode: 'TEST' and inspect the full response, including the status subcode and message.
4. Verify that your push URL is reachable from outside your network. Buckaroo sends push messages from fixed IP addresses and ports, so make sure these are on your allow list. See push messages for the current list.

Still stuck? Contact us and include your Node.js version, SDK version, the service and action you called, the error message and the transaction key.

• Bug reports and feature requests: open an issue
• Technical support: [email protected]
• Phone: +31 (0)30 711 50 50
• Gateway status: status.buckaroo.io

Contribute

We really appreciate it when developers help improve the Buckaroo SDKs. Please read our Contribution Guidelines before opening a pull request, and target the master branch.

Found a security issue? Please report it privately to [email protected] instead of opening a public issue.

Versioning

We follow semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR — breaking changes that require additional testing and caution.
• MINOR — new functionality with limited impact.
• PATCH — bug fixes and hotfixes only.

All changes are documented in the changelog and on the releases page.

License

This SDK is open source software licensed under the MIT license.

_{Made with care by Buckaroo.
This document is subject to change; typos and language errors are possible.}