Package Information
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-Keyheader. 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.