Node SDK

The Buckaroo Node SDK is an open source library that connects a JavaScript or TypeScript application to the Buckaroo API. It handles authentication, request signing and response parsing, so you can start payments, verify push messages, and refund or look up transactions with a few lines of code. TypeScript declarations are included.


Running a store on an e-commerce platform? Use one of our ready-made plugins and apps instead. This SDK is for custom applications.

Use the SDK on your server only. Never bundle it into a website or mobile app, because that exposes your secret key to everyone who loads the page.


Requirements

RequirementDetails
Buckaroo accountCreate an account if you do not have one yet
Node.jsAn actively supported LTS version
Package managernpm or yarn

Installation

npm install @buckaroo/buckaroo_sdk

Or with yarn:

yarn add @buckaroo/buckaroo_sdk

The source code is on GitHub.


Quick start

Create the client with your store key and secret key, then start a payment and send the customer to the payment page:

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

const buckaroo = Buckaroo.InitializeClient(
    {
        websiteKey: 'STORE_KEY', // your store key
        secretKey: 'SECRET_KEY',
    },
    {
        mode: 'TEST',
        currency: 'EUR',
        returnURL: 'https://example.com/buckaroo/return',
        pushURL: 'https://example.com/buckaroo/push',
    }
);

const response = await buckaroo
    .method('ideal')
    .pay({
        invoice: 'INV-1001', // must be unique per payment
        amountDebit: 10.0,
        description: 'Order #1001',
    })
    .request();

if (response.hasRedirect()) {
    // send the customer to response.getRedirectUrl()
}

That starts an iDEAL | Wero payment in test mode. The result of the payment arrives on your push URL, so continue with these pages in order:

  1. Configuration: credentials, test and live mode, defaults and timeouts
  2. Payments: start a payment, read the response and handle errors
  3. Push messages: receive and verify the payment result
  4. Order management: refunds, captures and transaction lookups
  5. Test and go live: what to test and how to switch to production

What you can build

The SDK covers the Buckaroo payment methods and the additional services such as Subscriptions, Credit Management, PayPerEmail, Split Payments and iDIN. Every method is called the same way, with its own service code.

  • Payment methods describes each method and its request parameters
  • The example folder in the repository has an example for each method, in JavaScript and TypeScript

Versioning

The SDK follows semantic versioning:

PartMeaning
MAJORBreaking changes that require additional testing and caution
MINORNew functionality with limited impact
PATCHBug fixes and hotfixes only

Every change is recorded in the changelog and on the releases page.


Contribute

The SDK is open source under the MIT license, and contributions are welcome. Read the contribution guidelines before you open a pull request.



Did this page help you?