Node.js client for the GoCardless API

A Node.js client for the GoCardless API. For full details of the GoCardless API, see the API docs.

PLEASE NOTE that this is intended only to be used in server-side code. Using it in client side code would expose your API key to your users.

If you are using React, we offer bindings in our react-dropin library.

Installation

$ npm i gocardless-nodejs

Usage

Initialising the client

To initialise the client, you must provide:

• An access token.
• The environment that this token is for (see here for a list of available environments).
• Any additional options (see here for a list of supported options).

import gocardless, { Environments } from 'gocardless-nodejs';

// Initialize the client
const client = gocardless(
  process.env.GC_ACCESS_TOKEN,
  Environments.Sandbox,
  { raiseOnIdempotencyConflict: true }
);

TypeScript:

import gocardless, { GoCardlessClient, Environments, Payment } from 'gocardless-nodejs';

const client: GoCardlessClient = gocardless(
  process.env.GC_ACCESS_TOKEN,
  Environments.Sandbox
);

const payment: Payment = await client.payments.find('PM123');

The Basics

We'll illustrate the basic library usage by demonstrating on the payment resource.

For a full list of available resources, visit the GoCardless API reference.

import { v4 as uuidv4 } from 'uuid';

// Create a new payment.
const payment = await client.payments.create(
  {
    amount: 100,
    currency: "GBP",
    links: { mandate: "MD123" },
  },
  uuidv4(),
);

// List the first three payments past a certain date.
const payments = await client.payments.list({
  limit: 3,
  created_at: {
    gt: '2020-01-01T17:01:06.000Z',
  },
});

// Get a payment.
const payment = await client.payments.find('PM123');

// Update a payment.
await client.payments.update('PM123', { amount: '22' });

// Cancel a payment.
await client.payments.cancel('PM123');

The all method

All resources with a list method will also have an additional *all method. This method acts like the regular list method and accepts the same parameters, but instead returns an async generator.

for await (const payment of client.payments.all()) {
  console.log(payment.id);
}

Available client options

• raiseOnIdempotencyConflict: set to true to raise exceptions on idempotency conflicts. Defaults to false.

CommonJS backwards compatibility

We provide a CommonJS implementation for backwards compatibility. For CommonJS, change the imports to:

const gocardless = require('gocardless-nodejs');
const { Environments } = require('gocardless-nodejs');

Handling webhooks

GoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:

• When a customer cancels their mandate with the bank, suspend their club membership
• When a payment fails due to lack of funds, mark their invoice as unpaid
• When a customer's subscription generates a new payment, log it in their "past payments" list

The client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into Event objects which are easy to work with:

import { webhooks } from 'gocardless-nodejs';

// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
const webhookEndpointSecret = process.env.GOCARDLESS_WEBHOOK_ENDPOINT_SECRET;

// In your webhook handler (e.g. Express route)
app.post('/webhooks', (req, res) => {
  try {
    const events = webhooks.parse(
      req.body,
      webhookEndpointSecret,
      req.headers['webhook-signature']
    );

    events.forEach((event) => {
      console.log(event.id);
    });

    res.status(200).end();
  } catch (e) {
    if (e.name === 'InvalidSignatureError') {
      // The webhook doesn't appear to be genuinely from GoCardless
      res.status(498).end();
    }
    throw e;
  }
});

Accessing the webhook ID

If you need to access the webhook ID for debugging purposes, you can use parseWithMeta instead:

const result = webhooks.parseWithMeta(
  req.body,
  webhookEndpointSecret,
  req.headers['webhook-signature']
);
const events = result.events;
const webhookId = result.webhookId;  // e.g. "WB123" - useful for debugging

Note: The webhook ID is intended for debugging and logging purposes only. It should not be used for deduplication - instead, use the event IDs to deduplicate, as each event has a unique ID that remains consistent if the same event is sent multiple times.

For more details on working with webhooks, see our "Getting started" guide.

Upgrading from older versions

If you're upgrading from v7 or earlier to v8 or later, see: MIGRATION_V8.md