How ERPNext collects recurring direct debits through GoCardless
Finance teams that need recurring collections against customer mandates can connect ERPNext to GoCardless through ERPNext's built-in GoCardless integration. Enabling the service requires an access token and, as the ERPNext documentation highly recommends, a webhook secret key. Together these let ERPNext talk to GoCardless for payment requests and receive the status updates that tell ERPNext when a collection has been paid, failed or cancelled, so the two credentials should be treated as production secrets from the first day.
Enabling GoCardless creates three records that finance should understand before go-live. ERPNext creates a Payment Gateway record, a bank-type account and a payment gateway account. The Payment Gateway record stores the connection for the site, the bank-type account is the ledger account that collections are posted to, and the payment gateway account links the two so that receipts and payment entries land in a known place. Review the account names, root type and currency on the bank-type account before any live collection, because changing them after transactions exist is difficult. Confirm with your accountant which chart of accounts and bank ledger the collections should reach.
Several GoCardless gateways can be configured on one ERPNext site, which matters when you run more than one GoCardless organization, separate legal entities or separate currencies. Each gateway needs its own credentials and its own gateway account, so map each one to the company and bank ledger it serves. Confirm in your own test environment whether your ERPNext version and GoCardless account setup support the currency and sandbox or live mode combinations you need, and plan how webhook endpoints are registered for each gateway. Mandate creation and collection rules sit outside what this section covers, so verify those steps against the GoCardless documentation and your payment process.
What you need before enabling GoCardless in ERPNext
Enabling GoCardless in ERPNext is a configuration step, but it depends on decisions made before anyone opens the Payment Gateway settings. The cards below cover the GoCardless credentials, the webhook choice, the ERPNext version and site, and the accounts that ERPNext will create and post to.
GoCardless access token
ERPNext needs a GoCardless access token to call the GoCardless API when it creates mandates and payments. Generate the token in the GoCardless dashboard for the correct environment, and store it in a secrets manager rather than in a shared document. Confirm with GoCardless's own documentation which token type and permissions your account issues, because the scope of the token determines what ERPNext can do on your behalf.
GoCardless environment: sandbox or live
Decide whether the first configuration targets the GoCardless sandbox or the live environment before any credentials are entered. Sandbox and live tokens are not interchangeable, and a gateway configured against the wrong environment will accept setup but fail when real mandates or payments are created. Keep a separate ERPNext test site for sandbox work so that live gateway records are created only once the flow has been verified.
Webhook secret decision
The ERPNext GoCardless documentation describes a webhooks secret key as highly recommended. Without it, ERPNext cannot verify that incoming GoCardless events came from GoCardless, so payment status updates depend on trust alone. Decide who generates the webhook secret in the GoCardless dashboard, where it is stored, and who rotates it, and record that decision before go-live.
Multiple gateway plan
ERPNext can be configured with several GoCardless gateways, which is useful when different companies, currencies or creditor accounts collect payments separately. List each intended gateway, its GoCardless account, and the ERPNext company it serves before you enable the first one. Each enabled service creates its own set of linked records, so unplanned gateways are harder to remove cleanly later.
ERPNext site and version
Confirm the ERPNext version and the Frappe Framework version your team runs on the target site, and check that the GoCardless integration is available for that version in the ERPNext documentation. Frappe's supported versions page lists the end-of-life dates for each release, so a site on an unsupported version should be planned for upgrade before adding a payment integration. Record the site name, the company names and the backup state before any change.
Chart of accounts ready for the bank account
Enabling the service creates a bank-type account and a payment gateway account, so the chart of accounts needs a sensible parent for the bank account and a clear clearing or receivable path for collected funds. Confirm with your accountant which account group, currency and company each new account belongs to. Changing these later means reposting or reclassifying ledger entries, which is slower to fix than setting them correctly at the start.
Configuring the GoCardless service step by step
This sequence connects ERPNext to a GoCardless account so that direct debit collections can be received and matched to invoices. Each step ends with a check you can run before moving on, so problems surface while the configuration is still small.
Obtain the GoCardless access token
Someone with administrator rights in the GoCardless dashboard creates or retrieves the access token that ERPNext will use to call the GoCardless API. Decide first whether the sandbox or live environment is the target, because the token is tied to one environment and the live token should only be issued once the test run is complete. Store the token in your organization's secrets process rather than in a shared document. The step is done when you hold a token for the intended environment and you can name the GoCardless account it belongs to.
Enable the GoCardless service in ERPNext
In ERPNext, open the GoCardless service setup from the list of available payment services and enable it. Enabling the service is what triggers ERPNext to create the supporting records, so do this on the site and in the company environment where collections will actually be booked. Confirm with the finance lead which company and currency the service will serve before enabling it, since the records created are tied to that setup. The step is done when the service shows as enabled and the setup form is open for the next entry.
Enter the access token in the setup form
Paste the access token from the first step into the access token field of the GoCardless setup and save the form. Check that the value was copied in full, with no leading or trailing spaces, since a truncated token usually fails only when the first API call is made. Limit who can view this field through role permissions. The step is done when the form saves without an error and the token field no longer shows as empty.
Add the webhook secret key
Create a webhook endpoint in the GoCardless dashboard that points to your ERPNext site, then copy the webhook secret key that GoCardless generates for it into the webhooks secret field in ERPNext. The GoCardless documentation for this integration highly recommends setting this key, because it lets ERPNext verify that incoming events really come from GoCardless. Save the form once the key is in place. The step is done when the endpoint is listed in GoCardless with the correct site address and the secret is saved in ERPNext.
Send a test webhook from GoCardless
Use the test event option in the GoCardless webhook settings to send a sample event to your ERPNext endpoint. Then check the webhook delivery log in GoCardless for a successful response, and check in ERPNext that the event was received and not rejected for a signature mismatch. If delivery fails, compare the endpoint address and the secret key before changing anything else. The step is done when GoCardless shows a successful delivery and ERPNext records the incoming event.
Verify the created payment gateway records
Enabling the service creates a Payment Gateway record, a bank-type account and a payment gateway account. Open each one and confirm it exists, is linked to the GoCardless service, and sits under the company and currency you selected. Check that the bank-type account is placed in the chart of accounts where your finance team expects bank balances, and that the payment gateway account points to it. Ask your accountant to review the account names before any payment is booked. The step is done when all three records exist with consistent links and the finance lead has signed off on their placement.
Add further GoCardless gateways the same way
If you run more than one GoCardless account, for example one per legal entity or currency, repeat the same sequence for each: obtain that account's token, enable the service, enter the token, add its own webhook secret and verify its three records. Keep each gateway's webhook endpoint and secret separate so that events are matched to the correct account. The step is done when every gateway has a passing test webhook and its own set of verified records.
What the Payment Gateway, bank account and ledger entries do
Enabling GoCardless in ERPNext creates three linked records: a Payment Gateway record, a bank-type account and a payment gateway account. The Payment Gateway record is the entry point that Payment Requests and the GoCardless service refer to. The payment gateway account ties that gateway to a currency and a company, and the bank-type account is the ledger account where the connector expects collected funds to sit. Check each of these after enabling the service, because the names ERPNext generates are defaults you can review, and the account types and parent accounts determine how the balances roll up in your chart of accounts.
Collected funds reach the ledger through Payment Requests. A Payment Request is raised against a sales invoice or order, and when the direct debit is paid, ERPNext records a Payment Entry that moves the amount from the receivable to the bank-type account linked through the gateway account. Decide the ledger mapping before go-live: which bank-type account each GoCardless gateway uses, which currency each one carries, and whether fees or failed collections need their own accounts. If you run several GoCardless gateways, a shared bank account across them makes reconciliation harder to trace back to a single creditor.
Confirm with your accountant how receivables and bank balances will be reconciled against the GoCardless payout reports and your bank statements, including timing differences between collection, payout and posting. Agree the treatment of partial collections, refunds and chargebacks before the first live run, since the connector's records alone do not settle those questions. DeployOpen can document the mapping and test entries in a non-production site, but the accounting treatment and the reconciliation policy are decisions your finance team and auditors must sign off.
When one GoCardless gateway is enough and when you need several
If one legal entity collects every direct debit in one currency through one GoCardless account, a single gateway is usually the simplest design. Enabling the service in ERPNext creates one Payment Gateway record, one bank-type account and one payment gateway account, and collected payments post to that bank ledger. Reconciliation stays in one place, and your finance team has one set of balances to check against the GoCardless payout reports.
- One bank ledger: All collections land in the bank account ERPNext created, so period-end checks compare one ledger against one payout stream.
- One access token: Only one set of GoCardless credentials and one webhook secret need to be stored, rotated and documented.
- Simpler customer records: Each customer's mandate is held against the single gateway, which keeps the Payment Request flow easy to follow for support staff.
- Clear ownership: One owner can answer questions about failed payments, retries and payouts without coordinating across accounts.
- Limit to watch: A single gateway does not separate revenue types, so subscription income and one-off invoices share one ledger unless you add accounting dimensions.
Before relying on this design, confirm with your finance lead that one bank ledger satisfies your reconciliation and audit needs.
When each company in your group holds its own GoCardless account, each one needs its own gateway configuration in ERPNext. Money collected for one entity must not settle into another entity's bank ledger, so the gateway and bank account should be set up against the company that owns the GoCardless account. This matters most when ERPNext runs several companies on one site, because the ledgers are kept separately by design.
- One gateway per GoCardless account: Each entity's access token and webhook secret belong to its own gateway record, not a shared one.
- Separate bank ledgers: Each gateway creates its own bank-type account under the matching company, so balances never mix between entities.
- Currency alignment: A GoCardless account typically collects in one currency, so confirm that each entity's gateway currency matches its ledger currency.
- Intercompany flows: If one entity sweeps funds to another, that transfer needs its own journal entries outside the gateway.
- Webhook routing: Each webhook endpoint must be registered with the matching GoCardless account, so events reach the correct gateway.
Confirm which GoCardless account owns each customer mandate before creating the gateways, because moving a mandate later is a separate exercise.
Within one company, subscriptions and one-off invoices can run through the same GoCardless account but still need separate reporting. A second gateway is one way to split them, though it is not always the best one. The choice depends on whether finance needs separate bank balances for each stream or only separate revenue reporting. Two gateways give you two bank ledgers; one gateway with accounting dimensions gives you one bank ledger and split revenue.
- Two gateways for two ledgers: Use this when the streams settle into different bank balances, for example to match separate payout records.
- One gateway with dimensions: Use this when only revenue needs splitting, and the bank balance can stay combined.
- Mandate handling: Recurring mandates belong to subscription customers, so confirm how one-off payments reference an existing mandate.
- Payment Request setup: Each Payment Request must point to the correct gateway, so staff need a clear rule for which gateway each invoice type uses.
- Reporting impact: Management reports will show bank balances differently, so agree the report layout before going live.
Document the rule for choosing a gateway per invoice type, and test one subscription and one one-off payment end to end before you rely on the split.
How GoCardless objects map to ERPNext records
This table shows which GoCardless credentials and objects land in which ERPNext records, and whether ERPNext creates each one or your team must define it. Read the last column first to see where your configuration work sits, then check the records column when you test a live mandate.
| GoCardless object | ERPNext record or setting | Created automatically or defined by your team |
|---|---|---|
| Access token | Stored in the GoCardless gateway configuration for each gateway record | Your team obtains and enters it; confirm the token type and environment (sandbox or live) with GoCardless before entry |
| Webhooks secret key | Stored in the GoCardless gateway configuration, used to verify incoming webhook requests | Your team sets it; the documentation highly recommends it, so treat it as required for production |
| GoCardless gateway (one per account) | Payment Gateway record | Created automatically when the service is enabled; confirm the gateway name is unique if you run several |
| GoCardless bank account | Bank-type account in the chart of accounts | Created automatically on enablement; your team should confirm its parent account and currency |
| Payment collection account | Payment Gateway Account linking the gateway to the bank-type account | Created automatically; your team should confirm which company and currency it serves |
| Customer mandate | Customer record and the mandate reference held against it | Your team must map each paying customer to an ERPNext Customer and confirm mandates exist before billing |
| Collected payment | Payment Entry and Payment Request posted against the Sales Invoice | Generated through the integration flow; your team sets the accounting treatment and reconciliation process |
| Multiple GoCardless accounts | Separate Payment Gateway and Payment Gateway Account pairs | Your team decides which gateway each company, currency or invoice series uses |
Protecting the access token and webhook secret
The GoCardless access token and webhook secret let ERPNext create and reconcile payments against your bank and customers. Each card below covers one control that keeps those credentials and the gateway settings that hold them out of reach of people and processes that do not need them.
Keep credentials out of shared documents
The access token and webhook secret are entered in the GoCardless settings in ERPNext and should not be pasted into Notes, comments, emails, chat threads or shared spreadsheets used for setup. Treat any export, backup or screenshot of those settings as sensitive. Check that your team uses a secrets manager or a restricted password vault for the original values, so the ERPNext record is the only working copy.
Restrict who edits gateway settings
Editing the GoCardless settings is a configuration change that can redirect payments, so limit it to a small set of finance or system administrators. Use ERPNext role permissions on the Payment Gateway and related account records, and confirm that users who can view payment requests cannot also change the gateway credentials. Review the role assignments after every staffing change.
Verify webhook signatures on every event
Reject any webhook whose signature does not match the webhook secret you configured. Without this check, anyone who can reach the endpoint could submit payment events that mark invoices as paid or create false bank entries. Confirm the signing header name, the algorithm and the exact body the signature covers in the GoCardless webhook documentation, and test a rejected request in a staging site before go-live.
Limit the GoCardless user's permissions
The access token belongs to a GoCardless user or application with its own permission scope. Ask GoCardless which scopes the token needs for mandates, payments and customers, and avoid a token with administrative rights over the whole account if read and create access is enough. Record which person or service owns the token so access can be removed when they leave.
Rotate credentials on a planned schedule
Plan rotation for both the access token and the webhook secret, and rehearse it on a test site first. Rotating the webhook secret without updating ERPNext causes every incoming event to fail verification, so coordinate the change window with finance, since payments may queue during it. Confirm the revocation and rotation steps, and whether old tokens stop working immediately, in the GoCardless documentation.
Log and review gateway changes
Keep an audit trail of who created or edited a GoCardless gateway, which accounts it is linked to, and when credentials changed. Review the ERPNext version history on Payment Gateway records and the webhook failure log regularly, since repeated signature failures can indicate a leaked or outdated secret. Decide in advance who receives alerts and who may disable a gateway in an incident.
Why GoCardless payments fail to appear in ERPNext
This table lists the failures that most often stop GoCardless payments from reaching ERPNext, with the likely cause and the check to run for each. Work down the rows in order, since a broken token or webhook secret blocks everything below it. The main takeaway is that most missing payments trace back to credentials, the webhook path or a gateway set up in the wrong place.
| Failure | Likely cause | Check to run |
|---|---|---|
| Access token rejected | The access token is wrong, expired, or was created in a different GoCardless environment than the one the gateway uses. | Confirm the token in the GoCardless Payment Gateway record matches the environment, then re-save it and run a test pull. |
| Webhook events never arrive | The webhooks secret key is missing, so ERPNext cannot verify incoming events and drops them. | Open the GoCardless Settings record, confirm the webhooks secret key is filled in, and compare it with the secret configured in the GoCardless dashboard. |
| Webhook URL not reachable | The site is behind a firewall, a private network, or an HTTPS certificate GoCardless cannot validate, so deliveries fail before reaching ERPNext. | Check the endpoint from outside your network, confirm TLS validity, and review delivery attempts and responses in the GoCardless dashboard. |
| Gateway enabled in the wrong environment | A sandbox token or sandbox setup was left active on a live site, or live credentials were tested against a sandbox account. | Verify the environment setting on the gateway, confirm which GoCardless account issued the token, and run one test payment in that environment only. |
| Payment does not match a Payment Request | The payment was created in GoCardless without a reference that ERPNext can link to an open Payment Request or invoice, so it stays unallocated. | Check the payment reference and metadata on the GoCardless side, then search Payment Requests by reference and confirm the amount and currency match. |
| Duplicate gateways post to the wrong account | Several GoCardless gateways point to different payment gateway accounts, or two records share a bank ledger, so receipts land in an unexpected account. | List every Payment Gateway and Payment Gateway Account record, confirm each one maps to the intended bank account and currency, and disable any leftover duplicates. |
Questions buyers ask before enabling GoCardless in ERPNext
Is the GoCardless integration in ERPNext free to use?
The ERPNext side is free. ERPNext is free and open source, so enabling the GoCardless service inside it does not add a license fee. GoCardless charges its own fees for processing direct debit payments, and those fees are set by GoCardless under your agreement with them, not by ERPNext. Ask GoCardless for its current fee schedule for your country and payment volume and confirm whether any setup or monthly charges apply. Your other costs are internal labor and, if you choose it, outside help, which is quoted separately from a written scope.
How long does GoCardless setup in ERPNext take?
The configuration itself is short once the credentials exist: you enter an access token, add a webhook secret key, and enable the service, which creates a Payment Gateway record, a bank-type account and a payment gateway account. The duration is driven by what surrounds it: getting a GoCardless account approved, creating the access token and webhook secret in the right environment, agreeing the chart of accounts mapping for the new bank ledger, and testing a full mandate-to-payment cycle. Teams with a clean chart of accounts and a test environment move faster than teams that must first redesign receivables.
What does the finance team need to provide?
Finance owns the decisions that the integration cannot make for you. They should confirm which company and currency each GoCardless gateway belongs to, which receivable account collects direct debit payments, and how the bank ledger created by the integration fits into their reconciliation process. They also need to decide how failed, cancelled and partially collected payments are posted, and who approves changes to those mappings. Without these answers, payments may land in accounts that are hard to reconcile at period close.
What does the IT team need to provide?
IT is responsible for the secure handling of the access token and webhook secret key. Store them in a controlled location, restrict who can view them in ERPNext, and rotate them through a documented process. IT must also make sure the ERPNext site is reachable from GoCardless so webhook events arrive, and that the site's TLS configuration is current. If the site runs on Frappe Cloud or in your own cloud or data center, confirm with the team responsible for that hosting how inbound webhook traffic is allowed through firewalls and proxies.
Can our team set up GoCardless in ERPNext without outside help?
Yes, a team with ERPNext administration experience can enable the integration using the official GoCardless documentation. The configuration screens are not the hard part. The risk sits in the surrounding decisions: account mapping, multi-gateway design, webhook verification and testing against real mandates. If your team has already built a payments reconciliation process and has someone who has configured ERPNext accounts before, an internal rollout is a reasonable choice. If no one on the team has handled payment gateway accounts, the first live collections are the wrong time to learn.
When is it worth bringing in a partner for GoCardless in ERPNext?
A partner is worth considering when the setup extends beyond a single gateway: several GoCardless gateways for different companies or currencies, custom mapping for recurring billing, a migration of existing mandates, or a need to prove controls to auditors. A fixed-scope engagement starts with a written list of deliverables, such as the gateway design, account mapping, webhook test plan and handover notes, and produces a quote from that scope. DeployOpen implements and documents self-hosted ERPNext inside your own infrastructure and prepares evidence for compliance assessments, but it does not issue audit reports or certifications.
Does a multi-gateway setup change the effort?
Yes. ERPNext lets you configure several GoCardless gateways, and each one creates its own Payment Gateway record, bank-type account and payment gateway account when enabled. Every additional gateway adds mapping decisions, test cases and reconciliation work. The effort grows with the number of companies, currencies and bank accounts involved, and with how many webhook secrets must be managed. Ask for the gateway design to be written down before configuration starts, so each gateway's purpose and ledger destination is clear.
What recurs after GoCardless is enabled in ERPNext?
Recurring work includes reviewing failed and cancelled payments, reconciling the GoCardless bank ledger against the bank statements, rotating credentials, and checking that webhook events are still arriving after any hosting, firewall or ERPNext upgrade. Plan for ERPNext upgrades to be tested against the payments flow, since version changes can affect integrations. Ask whether your internal owner or a retainer will cover this monitoring, and what happens when a webhook fails.
How DeployOpen scopes and delivers the GoCardless integration
DeployOpen plans, implements, tests and documents ERPNext and GoCardless direct debit integration inside your own infrastructure, using a written scope agreed before work starts. Each step below shows what you receive and what your team needs to decide, so the integration can be reviewed, operated and supported after handover.
How we scope
- Engagements are fixed-scope, with the GoCardless gateways, currencies and sites to be connected agreed in writing first.
- We record which ERPNext company, bank-type account and payment gateway account each GoCardless gateway will feed.
- We confirm where access tokens and webhook secret keys will be stored, and who in your organization holds them.
How we build
- We configure each GoCardless gateway in ERPNext and check the Payment Gateway, bank and payment gateway account records it creates.
- We test webhook delivery to your ERPNext site, including a rejected request with an incorrect secret, before any live mandate is used.
- We reconcile test payments against the bank ledger so posting, rounding and currency behavior match your accounting policy.
How we hand over
- You receive a configuration record listing each gateway, account mapping, webhook endpoint and the owner responsible for each credential.
- We document the test cases used, the expected ledger entries and the steps to rotate the access token or webhook secret.
- We walk your finance and platform staff through a payment cycle so they can explain each entry during period close.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the build.
- Recurring costs include the GoCardless account fees you pay directly and any retainer you choose, both to be confirmed in your quote.
- Before each ERPNext upgrade, we retest webhook handling and gateway posting, so payment collection is not interrupted unexpectedly.
