GitHub - gocardless/gocardless-nodejs: GoCardless Node.js client

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 from 'gocardless-nodejs';
import { Environments } from 'gocardless-nodejs/constants';

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

TypeScript:

import gocardless, { GoCardlessClient } from 'gocardless-nodejs';
import { Environments } from 'gocardless-nodejs/constants';
import type { Payment } from 'gocardless-nodejs/types';

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/constants');

Upgrading from older versions

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