gocardless

n8n community node for the GoCardless Payments API

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 1.0.2
Author: Robert Wall | T4DT GmbH

Documentation

@t4dt/n8n-nodes-gocardless

n8n community nodes for the GoCardless Payments API (API version 2015-07-06).

Node Style Purpose
GoCardless declarative All 45 resources and 133 operations of the Payments API
GoCardless Trigger programmatic (webhook) Starts workflows from GoCardless webhooks, signature verified
GoCardless Events Trigger programmatic (polling) Starts workflows from new events without a public URL

The action node is built in the declarative style: every operation is described through requestDefaults and routing. Custom code is limited to small, tested routing hooks in lib/routing/. The triggers are programmatic because n8n requires webhook() / poll() methods.

Installation

Follow the community nodes installation guide and install @t4dt/n8n-nodes-gocardless.

Credentials

GoCardless API

Create an access token in the GoCardless dashboard under Developers → Create → Access token.

Field Description
Environment Sandbox or Live
Access Token Read-write or read-only token
Sign Requests Signs every request (needed for outbound payments)
Public Key ID / Private Key (PEM) Key pair registered in GoCardless (ECDSA secp521r1)

The credential test calls GET /creditors?limit=1.

GoCardless Webhook API

The secret of a webhook endpoint created in the dashboard under Developers → Create → Webhook endpoint.

Operations

Resource Operations
Balance Get Many
Bank Account Detail Get
Bank Account Holder Verification Create, Get
Bank Authorisation Create, Get
Bank Details Lookup Create
Billing Request Cancel, Choose Currency, Collect Bank Account, Collect Customer Details, Confirm Payer Details, Create, Fallback, Fulfil, Get, Get Many, Notify, Select Institution
Billing Request Flow Create, Initialise
Billing Request Template Create, Get, Get Many, Update
Billing Request With Action Create With Actions
Block Block By Ref, Create, Disable, Enable, Get, Get Many
Creditor Create, Get, Get Many, Update
Creditor Bank Account Create, Disable, Get, Get Many
Currency Exchange Rate Get Many
Customer Create, Get, Get Many, Remove, Update
Customer Bank Account Create, Disable, Get, Get Many, Update
Customer Notification Handle
Event Get, Get Many
Export Get, Get Many
Funds Availability Check
Instalment Schedule Cancel, Create With Dates, Create With Schedule, Get, Get Many, Update
Institution Get Many, Get Many for Billing Request
Logo Create For Creditor
Mandate Cancel, Create, Get, Get Many, Reinstate, Update
Mandate Import Cancel, Create, Get, Submit
Mandate Import Entry Create, Get Many
Mandate PDF Create
Negative Balance Limit Get Many
Outbound Payment Approve, Cancel, Create, Get, Get Many, Stats, Update, Withdraw
Outbound Payment Import Create, Get, Get Many
Outbound Payment Import Entry Get Many
Payer Theme Create For Creditor
Payment Cancel, Create, Get, Get Many, Retry, Update
Payment Account Get, Get Many
Payment Account Transaction Get, Get Many
Payout Get, Get Many, Update
Payout Item Get Many
Redirect Flow Complete, Create, Get
Refund Create, Get, Get Many, Update
Scenario Simulator Run
Scheme Identifier Create, Get, Get Many
Subscription Cancel, Create, Get, Get Many, Pause, Resume, Update
Tax Rate Get, Get Many
Transferred Mandate Get
Verification Detail Create, Get Many
Webhook Get, Get Many, Retry

Payer Authorisations are deprecated by GoCardless and not included.

Behaviour

  • Amounts are sent in minor units (e.g. cents): 1000 = 10.00 EUR.
  • Idempotency: every create request carries an Idempotency-Key header. Leave Options → Idempotency Key empty for a random UUID.
  • Metadata: up to 3 key-value pairs (key ≤ 50, value ≤ 500 characters), validated before the request.
  • Nested attributes (e.g. mandate_request.scheme) are separate fields; arrays of objects are entered as JSON.
  • Return All follows GoCardless cursor pagination with a page size of 500 and keeps all filters.
  • Rate limits: GoCardless allows 1,000 requests per minute. Enable Retry On Fail in the node settings (e.g. 3 tries, 60 s wait) for large batches.

Triggers

GoCardless Trigger – create a webhook endpoint in the GoCardless dashboard with the node's production URL. Requests with an invalid Webhook-Signature are answered with 498; batches without matching events with 204. Each event becomes one item. Optionally the affected resource (e.g. the payment) is loaded and added as resource. GoCardless retries failed deliveries, so use the event id to deduplicate.

GoCardless Events Trigger – polls GET /events. The first activation starts from "now"; afterwards every event created since the last poll is emitted once, oldest first.

Both triggers filter by resource type and action (comma-separated, e.g. confirmed, paid_out).

Development

npm install --ignore-scripts
npm run dev        # n8n with the nodes loaded
npm run lint       # n8n community node rules (strict mode)
npm run typecheck  # strict TypeScript incl. tests
npm test           # vitest
npm run generate   # regenerate descriptions from the gocardless-nodejs SDK
npm run build

Project layout:

credentials/                       GoCardlessApi (+ request signing), GoCardlessWebhookApi
nodes/GoCardless/                  node entries
nodes/GoCardless/descriptions/     hand-written descriptions (core resources)
nodes/GoCardless/descriptions/generated/   generated from the SDK – do not edit
lib/routing/                       preSend / pagination / signing hooks
lib/shared/                        constants and builders for fields and operations
lib/trigger/                       trigger repositories, services, view model, factories
lib/types/                         shared types
scripts/generate-descriptions.mts  description generator
test/                              unit tests incl. SDK coverage and signing cross-checks

The generator reads HTTP method, path, envelopes and request fields from the official SDK gocardless-nodejs (dev dependency). After an SDK update run npm run generate and npm test: test/sdkCoverage.test.ts fails if any SDK endpoint is missing in the node.

License

MIT

Discussion