{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",
    "esModuleInterop": true,
    "strict": true
  }
}

3. Environment variables. Set your GoCardless access token:

GC_ACCESS_TOKEN=your_sandbox_or_live_token
GC_ENVIRONMENT=sandbox   # or "live"

4. Instantiate the client once at application startup and reuse it:

import gocardless from './gocardless/index.js';
import { Environments } from './gocardless/constants.js';

export const gc = gocardless(
  process.env.GC_ACCESS_TOKEN!,
  process.env.GC_ENVIRONMENT === 'live' ? Environments.Live : Environments.Sandbox,
  { raiseOnIdempotencyConflict: true }
);

5. CommonJS projects. If you are not using ESM, the upstream package ships a CJS build; adjust imports to require() style. With the source directly, compile via tsc first or use a bundler.

Public API

gocardless (default export)

function gocardless(
  token: string,
  environment?: Environments,
  options?: APIOptions
): GoCardlessClient

Factory function. Call once with your API token and target environment. APIOptions accepts raiseOnIdempotencyConflict: boolean to control idempotency error behaviour. Returns a fully configured GoCardlessClient.

GoCardlessClient

class GoCardlessClient {
  payments: PaymentService;
  mandates: MandateService;
  customers: CustomerService;
  customerBankAccounts: CustomerBankAccountService;
  subscriptions: SubscriptionService;
  payouts: PayoutService;
  refunds: RefundService;
  billingRequests: BillingRequestService;
  events: EventService;
  webhooks: WebhookService;
  // ... all other resource services
}

The central client object. Access every GoCardless resource through its property (e.g. client.payments.create(...)). All service methods return Promises.

Environments

enum Environments {
  Live = 'LIVE',
  Sandbox = 'SANDBOX'
}

Pass to the gocardless() factory. Use Environments.Sandbox during development and Environments.Live in production. Do not hard-code the string values.

parse / verifySignature

function parse(body: string): object;
function verifySignature(body: string, secret: string, signature: string): void; // throws InvalidSignatureError

Use in your webhook endpoint. parse deserialises the raw request body; verifySignature validates the Webhook-Signature header against your webhook secret. Throws InvalidSignatureError on mismatch.

toMetadata / toMetadataValue

function toMetadata(obj: Record<string, unknown>): { [key: string]: string };
function toMetadataValue(value: unknown): string;

GoCardless metadata values must be strings. Use toMetadata to convert an object with mixed value types before passing to any create/update call.

Working examples

Scenario - Create a customer and payment

Create a customer, attach a bank account via mandate, then create a one-off payment against that mandate.

import { v4 as uuidv4 } from 'uuid';
import { gc } from './gcClient.js';
import { toMetadata } from './gocardless/metadata-helpers.js';

async function chargeCustomer() {
  const customer = await gc.customers.create({
    email: 'buyer@example.com',
    given_name: 'Jane',
    family_name: 'Smith',
    address_line1: '1 Somewhere Lane',
    city: 'London',
    postal_code: 'SW1A 1AA',
    country_code: 'GB',
    metadata: toMetadata({ internal_id: 9001, vip: true }),
  });

  const payment = await gc.payments.create(
    {
      amount: 1000, // pence
      currency: 'GBP',
      description: 'Monthly subscription',
      links: { mandate: 'MD_EXISTING_MANDATE_ID' },
      metadata: toMetadata({ order_id: 'ORD-42' }),
    },
    uuidv4(), // idempotency key
  );

  console.log('Payment created:', payment.id);
}

Scenario - Handle incoming webhooks in Express

Verify and process GoCardless webhook events in an Express route.

import express from 'express';
import { parse, verifySignature, InvalidSignatureError } from './gocardless/webhooks.js';

const app = express();

app.post('/webhooks/gocardless', express.text({ type: '*/*' }), (req, res) => {
  const signature = req.headers['webhook-signature'] as string;
  const secret = process.env.GC_WEBHOOK_SECRET!;

  try {
    verifySignature(req.body, secret, signature);
  } catch (err) {
    if (err instanceof InvalidSignatureError) {
      return res.status(498).send('Invalid signature');
    }
    throw err;
  }

  const events = parse(req.body) as { events: Array<{ resource_type: string; action: string }> };

  for (const event of events.events) {
    console.log(`Event: ${event.resource_type} / ${event.action}`);
    // handle payment_paid_out, mandate_cancelled, etc.
  }

  res.status(204).send();
});

Scenario - Paginate all payments with the async generator

Use the all() method to iterate every payment without manual cursor management.

import { gc } from './gcClient.js';
import type { Payment } from './gocardless/types/Types.js';

async function exportAllPayments(): Promise<Payment[]> {
  const results: Payment[] = [];

  for await (const payment of gc.payments.all({ status: 'paid_out' })) {
    results.push(payment);
  }

  console.log(`Total paid-out payments: ${results.length}`);
  return results;
}

File walkthrough

• index.ts — Re-exports the gocardless factory, GoCardlessClient, Environments, webhook utilities, and metadata helpers; this is the package's public surface.
• client.ts — Instantiates every service class and exposes them as properties; holds the single Api instance shared across services.
• api/api.ts — Wraps got for authenticated HTTP requests; injects Authorization, idempotency keys, and handles rate-limit and error parsing.
• constants.ts — Declares Environments, CLIENT_VERSION, and API_VERSION constants used internally and exported for consumer use.
• errors.ts — Defines the error hierarchy: GoCardlessException → ApiError (structured API errors) and MalformedResponseError; ApiError.buildFromResponse is used internally.
• webhooks.ts — Implements HMAC-SHA256 signature verification and JSON parsing for inbound webhook payloads; exports parse, verifySignature, InvalidSignatureError.
• apiRequestSigning.ts — ApiRequestSignatureHelper constructs HTTP message signatures for outbound payment signing flows; uses crypto and uuid.
• metadata-helpers.ts — Convenience functions to coerce arbitrary values into GoCardless's required { [key: string]: string } metadata shape.
• services/ — One class per GoCardless resource; each service class receives the shared Api instance and maps methods (create, find, list, all, update, cancel, etc.) to API endpoints.
• types/Types.ts — Single file of TypeScript interfaces and enums for all request params and response objects; import types from here for full type safety.

Common pitfalls and fixes

• ESM .js extensions in imports. The source uses import ... from './foo.js' throughout. If your bundler or TypeScript config does not support this, set "moduleResolution": "Node16" or "Bundler" in tsconfig.json.
• Raw body required for webhook verification. Express parses bodies to objects by default; use express.text({ type: '*/*' }) or express.raw() on the webhook route so verifySignature receives the original string.
• Missing GC_ACCESS_TOKEN at runtime. The client will initialise but every request will return a 401; always validate process.env.GC_ACCESS_TOKEN is defined before constructing the client.
• Idempotency keys. Omitting the second argument to payments.create() means GoCardless auto-generates a key, but retrying the same logical operation without a stable key can create duplicate payments. Always pass uuidv4() stored against your order.
• Sandbox vs Live environments. Tokens are environment-specific; a Sandbox token passed with Environments.Live will always fail. Use Environments.Sandbox for all non-production work.
• Metadata values must be strings. Passing { user_id: 123 } directly to the API will result in a validation error; use toMetadata({ user_id: 123 }) to convert before passing.

Vibe-coding prompt template

I have the GoCardless Node.js SDK source in `source/` and a usage guide in `USAGE.md`.
The upstream package is `user@example.com`.

Please integrate this SDK into my project step by step:

1. Read USAGE.md fully before writing any code.
2. Install all required runtime dependencies listed in USAGE.md.
3. Create a singleton GoCardlessClient using the `gocardless` factory from `source/index.ts`,
   reading credentials from environment variables GC_ACCESS_TOKEN and GC_ENVIRONMENT.
4. Implement the following feature using the real service methods on the client: [DESCRIBE YOUR FEATURE].
5. Add webhook handling using `parse` and `verifySignature` from `source/webhooks.ts`
   on the route POST /webhooks/gocardless, ensuring the raw body is preserved.
6. Use `toMetadata` from `source/metadata-helpers.ts` wherever metadata is passed to the API.
7. Handle `ApiError` from `source/errors.ts` with appropriate HTTP response codes.
8. Use TypeScript types from `source/types/Types.ts` for all resource objects.
9. Do not invent any methods or exports; only use what is documented in USAGE.md and visible in source/.

License and credit

The upstream source is published by GoCardless under the MIT License. See source/LICENSE if present, or refer to the npm package page and the GitHub repository for the full license text and changelog.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Twilio Node.js SDK for SMS and Voice APIs

Automation, Utilities & Developer Tools

Free