What the ERPNext payment gateway integration does for your receivables
Finance teams that issue invoices from ERPNext but collect payment outside it end up matching cash by hand, comparing bank deposits, gateway reports and open invoices line by line. The payment gateway integration closes that gap by attaching an online payment provider to a Payment Request, so a customer pays the request and the provider's confirmation drives the resulting Payment Entry in ERPNext. The gateway confirmation, not the customer's click, should create the accounting record, which is the control that matters most to your auditors and to your receivables team.
The documented connectors today include Stripe and GoCardless, and the Frappe Payments app is the place where other gateways such as Razorpay, PayPal, Braintree, M-Pesa, Paytm and Paymob are provided. Each gateway has its own account setup, supported currencies, webhook behavior and fee handling, so confirm each one against its current documentation and your own test account before you commit to it. The Stripe setup guide and the GoCardless setup guide are the natural starting points for the two connectors with published documentation. This page walks through the method, the prerequisites, the configuration order, how gateway fields map to ERPNext documents, the security controls around API keys and webhook secrets, testing, and the failure points that show up in reconciliation. Read it as a plan: decide which gateways your customers need, which currencies and accounts they settle into, and who owns exceptions before anyone configures a live key.
What you need in place before configuring any gateway
Gateway configuration is the last step, not the first. The checks below cover the ERPNext and Frappe versions, the hosting model, the merchant accounts, the public endpoint that gateways call back to, and the finance decisions about where money lands. Settle these with the people who own each one before anyone opens a gateway settings page.
Confirm the ERPNext and Frappe version
Check that your ERPNext and Frappe Framework release is on Frappe's supported versions list before you build payment flows on it. Version 14 reached end of life on January 31, 2026, so a site still on that line needs an upgrade plan first. Also confirm which Payments app version your release ships and which gateways it includes, because gateway support differs between releases and the gateway you need may not be in your build.
Decide the hosting model and support cover
Choose between Frappe Cloud, Docker Compose and bench, since each changes who patches the stack and who holds the database backups. Frappe's policy ties warranty coverage to running a listed version with a matching Frappe Cloud support plan, so a self-hosted site outside that arrangement needs its own support path. Ask whether your hosting choice also covers public HTTPS, background workers and the scheduler, because payment webhooks depend on all three.
Name the merchant account owner
Each gateway account belongs to a legal entity, and that entity must be able to receive settlements and approve API key changes. Name one owner who controls the Stripe, Razorpay or other merchant dashboard, holds the API credentials, and can rotate them after a staff change. Record who is allowed to enable live mode, because a test key left in production or a live key shared across sites causes the most avoidable failures.
Open accounts for each currency
Plan one gateway account per currency and per settlement bank account you intend to use, rather than assuming one account handles everything. Confirm each gateway's supported currencies and any currency limits with the provider, since these are set by the provider and can change. ERPNext ties each payment gateway account to a currency, so a missing currency account stops payments at the point of sale or checkout.
Provide a public HTTPS webhook endpoint
Gateways send payment status events to a public HTTPS address, so the site must be reachable from the internet with a valid certificate and a stable hostname. Keep the webhook path open through any reverse proxy, WAF or IP allowlist, and confirm that internal-only DNS or VPN access will not block provider callbacks. Test the endpoint from outside your network before go-live, because a site that only works inside your network will show payments as pending indefinitely.
Agree how payments post to the ledger
Finance should sign off on which bank and receivable ledger accounts each gateway posts to, including how gateway fees, refunds and currency differences are recorded. Decide who reconciles gateway payouts against bank statements and how often, so unmatched settlements do not accumulate. Document this mapping before configuration, because changing it later means correcting posted entries rather than editing a setting.
Configuring the gateway in the order that avoids reconciliation gaps
This sequence connects the provider account, the ERPNext gateway account, credentials and webhooks in an order that keeps every online payment traceable to a Payment Entry and a ledger line. Each step ends with a check so that gaps surface during setup rather than at month end.
Confirm the provider account and currency settings
Before touching ERPNext, the finance lead or the account owner confirms in the provider's dashboard which legal entity the account belongs to, which settlement currency it pays out in, and whether test or sandbox mode is available for the account. Write these down, because the currency of the ERPNext Payment Gateway Account must match what the provider settles. Ask the provider which currencies and payment methods the account is enabled for, since these limits decide which Payment Requests can succeed. Done means you have a one-page record of entity, settlement currency, enabled methods and the test mode location, confirmed by someone who can log in to the dashboard.
Create the Payment Gateway Account in ERPNext
A finance administrator creates the Payment Gateway record for the chosen gateway, then the matching Payment Gateway Account with the same currency as the provider settlement currency. Map the receiving bank account or the receivable side as your chart of accounts requires, and confirm with your accountant which account clearing payments should land in before settlement. Keep one gateway account per provider account and currency so that settlements can be matched cleanly. Done means the account saves without a currency mismatch and appears as the default option on a test Payment Request, which you can check in the Payment Request form without sending it.
Store API keys and the webhook signing secret
Using the provider's dashboard, an administrator creates restricted or test API keys with the smallest permissions the integration needs, then enters them into the gateway settings in ERPNext. Generate the webhook signing secret in the provider dashboard at the same time and store it in the same settings record, never in a shared spreadsheet or chat thread. Limit who can view these fields, and record which key version is live. Done means the settings save and a read-only connection check passes, while the provider dashboard shows the key as used by your site.
Register the webhook URL with the provider
Copy the webhook endpoint shown in the ERPNext gateway configuration and register it in the provider dashboard for the events that drive payment status, such as successful charges, failed charges and refunds. Confirm that the URL uses HTTPS and that it resolves publicly to the site, because providers cannot deliver events to an internal address. Use the webhook signing secret from the previous step so that ERPNext can verify each delivery. Done means the provider dashboard reports a successful test delivery to the endpoint, and the ERPNext webhook log shows the event received.
Run a test payment in sandbox or test mode
Where the provider offers a sandbox or test mode, a tester creates a small Payment Request in ERPNext against a test customer and pays it with the provider's test card or test method. Use only the test keys in this run, and do not mix them with live credentials. Watch the Payment Request status, the provider event history and the webhook log in sequence, and note any event that arrives out of order or without a matching request. If the provider has no test mode for a specific method, ask the provider which production-safe check it recommends. Done means the Payment Request moves to paid status through the webhook, not through a manual update.
Verify the Payment Entry and ledger lines
After the test payment, an accountant opens the Payment Entry that ERPNext created and checks the paid amount, currency, exchange rate if any, the customer and the linked Sales Invoice or Payment Request reference. Then review the General Ledger for the bank or clearing account and the receivable account, and confirm that the debit and credit lines balance and carry the same reference. Repeat the check for a refund or a failed payment if the provider sends one. Done means every test transaction has one Payment Entry, the ledger lines net to the expected amount, and the provider's gross, fee and net figures can be traced to the ERPNext entries before live use.
Confirm settlement matching before going live
Before enabling live keys, the finance lead agrees with the provider how payouts arrive, whether fees are deducted from the payout or recorded separately, and how the settlement report maps to the clearing account. Ask the provider for a sample settlement report and reconcile the test entries to it by hand. Switch to live keys only after this reconciliation has been signed off, and rerun one small live payment with a known outcome. Done means the signed reconciliation note names the gateway account, the settlement schedule and the fee treatment, and the live check produces the same ledger pattern as the test run.
How ERPNext records map to gateway objects and ledger entries
This table compares each ERPNext record involved in an online payment with the matching object at the gateway and the ledger entry finance expects. Read it as a checklist for your build: confirm each ERPNext field name against the version you install, then confirm the gateway object names in the provider's dashboard before you map anything in code. The main takeaway is that the Payment Request, the gateway reference and the fee lines must all tie back to one another, or reconciliation becomes manual work.
| ERPNext record | Gateway object | What finance needs from the mapping |
|---|---|---|
| Payment Request | Charge, payment intent or checkout session | One Payment Request per payable invoice or order, with the gateway's charge ID stored against it so a webhook can find the right document. |
| Payment Gateway Account | Provider account and settlement currency | Each gateway account names one provider account and one currency; confirm how multi-currency sites split these accounts before go-live. |
| Payment Entry reference | Gateway payment or settlement reference | The provider's transaction ID goes into the reference field so the bank line and the Payment Entry can be matched later. |
| Fee and payout amounts | Balance transaction, fee or payout record | Gateway fees post to a separate expense or clearing account, and the net payout matches a bank deposit; confirm the account names with your accountant. |
| Subscription plan (Stripe) | Stripe subscription and price | A Frappe payment plan is linked to a Payment Request marked as a subscription; confirm the plan and subscription field names in your installed version. |
| Mandate (GoCardless) | Direct debit mandate | The customer validates a SEPA mandate once, and later Payment Requests use that mandate; store the mandate reference against the customer for audit. |
| Webhook event | Gateway event and event ID | Each processed event updates the Payment Request status; record the event ID so a retried webhook does not create a second Payment Entry. |
What the Stripe and GoCardless documentation covers today
The ERPNext documentation describes two gateway connectors in enough detail to plan around. The Stripe connector can take a Payment Request that is marked as a subscription and create a Stripe subscription from it, using payment plans defined in Frappe. That makes Frappe, not the Stripe dashboard, the place where recurring amounts and billing intervals are defined, so finance staff need to agree which system owns plan changes and how a plan edit in Frappe reaches existing subscribers. The GoCardless connector works differently for SEPA Direct Debit. The customer validates a mandate once, and later Payment Requests go directly to GoCardless without asking the customer to approve each payment again. The integration supports several GoCardless gateways within one ERPNext site, and the documentation recommends setting a webhooks secret so that incoming GoCardless events can be verified before ERPNext acts on them.
The supplied documentation does not cover every gateway in the Payments app. Razorpay, PayPal, Braintree, M-Pesa, Paytm and Paymob each have their own settings, currency rules and webhook events, and the reader should not assume they match Stripe or GoCardless. Before committing to a gateway, confirm with the vendor's current documentation and with the Payments app version installed on your ERPNext release which currencies and payment methods are supported, which subscription or recurring features exist, which webhook events are sent and whether ERPNext handles them. Test each gateway against a sandbox account and a real Payment Request, and record the answers in your design document. Treat any gap as a scope question for the quote, not an assumption to resolve during go-live.
Choosing the payment pattern: one-off, subscription or direct debit
A one-off payment is the simplest pattern: ERPNext creates a Payment Request against a Sales Invoice or order, the customer pays once through the gateway, and the payment is recorded against that invoice. The configuration centers on the Payment Gateway Account for each provider, the currency it accepts, and the email template that carries the payment link. Because nothing recurs, the main work is confirming that each gateway account matches the currency and bank account finance expects.
- Gateway account per currency: Confirm whether the provider settles in the currency of each invoice, or whether conversion happens at the gateway and changes the amount received.
- Customer experience: The customer receives a link, pays on the gateway's hosted page, and sees a confirmation. Check the return and failure URLs during testing.
- Partial and failed payments: Decide how a declined card or partial amount is handled, and whether the Payment Request stays open for a retry.
- Reconciliation: Match each gateway payout to the Payment Entry and the bank ledger, including any gateway fees the provider deducts before settlement.
Confirm with the gateway which currencies and payout schedules apply to your account before you design the reconciliation routine.
For recurring billing, the Payment Request is marked as a subscription and tied to a payment plan defined in Frappe. The Stripe integration can create Stripe subscriptions from such a request, so the billing schedule lives with the gateway while ERPNext keeps the invoice and accounting record. This pattern needs more upfront design because the plan, the customer's card or payment method, and the invoice cycle must agree.
- Payment plan design: Define the billing interval, amount and tax treatment in ERPNext so that each generated invoice matches the subscription price.
- Failed renewals: Decide who chases a failed renewal, how many retries the gateway performs, and when the customer's subscription is paused or cancelled.
- Plan changes and cancellations: Document how upgrades, downgrades and mid-cycle cancellations are reflected on both the gateway and the ERPNext invoice.
- Revenue and receivables: Finance must reconcile each renewal against an invoice, and treat failed or disputed renewals as open receivables rather than income.
Confirm with your Stripe account team and your finance lead how proration and dunning will be handled before you enable subscriptions in production.
SEPA direct debit through GoCardless works differently. The customer validates a mandate once, and later payment requests go directly to GoCardless rather than asking the customer to pay each time. Setup therefore includes the access token, the webhook secret and the mandate flow, and the payment gateway account and bank ledger that ERPNext creates for the collections. The customer sees a one-time mandate approval followed by automatic collections on agreed dates.
- Mandate lifecycle: Track mandates that are cancelled, expired or changed by the customer, because a collection against an invalid mandate fails.
- Webhook handling: Configure the webhook secret so that payment status changes reach ERPNext, and confirm which events update the Payment Entry.
- Failed or reversed collections: Plan how bounced or charged-back debits are reversed in the ledger and communicated to the customer.
- Collection timing: Finance should reconcile against the dates the scheme settles funds, not the dates ERPNext requests them, and plan for the gap between the two.
Confirm the mandate rules and collection schedule with GoCardless for the countries and currencies you intend to use.
Securing webhooks, keys and currency limits
Payment gateway integrations sit at the boundary between your ERP, your customers and external processors. The controls below decide whether a forged webhook can mark an invoice paid, whether a gateway key leaks through a script, and whether ERPNext ends up in card data scope it never needed.
Keep gateway keys out of scripts
Store gateway API keys and the webhook secret in the site configuration or in a managed secrets store, never in Server Scripts, custom app code or exported customizations that travel with the codebase. Rotate them through the same change process you use for other production credentials, and confirm who can read the site configuration file on each bench host. Ask your gateway provider which key types are restricted (publishable versus secret) and scope each key to the minimum the integration needs.
Restrict Payment Gateway Account roles
Anyone who can edit a Payment Gateway Account can change the target account, the mode (test or live) or the credentials that receive money. Limit that role to a small finance-systems group, separate it from users who create Payment Requests, and review role assignments on a schedule. Confirm that changes to gateway accounts appear in the version history you rely on for audit.
Verify webhook signatures before changes
Every incoming webhook should be checked against the gateway's signature or the shared webhook secret before it changes a Payment Entry, Payment Request or invoice status. Reject unsigned and replayed events, and log the rejections. Confirm with your gateway how it signs events, which timestamp tolerance it uses, and how it retries failed deliveries so that a duplicate event does not create a second payment.
Secure the webhook endpoint
The webhook endpoint must accept traffic only over TLS, and your reverse proxy should keep access logs that record source address, path, status and time for each call. Restrict the endpoint to the gateway's published sending ranges where the provider publishes them, and alert on bursts of rejected requests. Confirm that the logs are retained long enough for your reconciliation and incident process.
Confirm card data stays with the provider
Design the flow so card numbers are entered on hosted pages or elements controlled by the gateway, and ERPNext stores only tokens, payment identifiers and status. Ask the gateway for its attestation of compliance and the responsibility matrix for your integration type, then confirm with your assessor how your environment is scoped. Do not build any custom form that collects card details on your own servers without a separate scope review.
Check currency limits per gateway
Before quoting a customer in a foreign currency, confirm which currencies each gateway supports and which currencies each Payment Gateway Account accepts. A mismatch between the invoice currency, the gateway currency and the bank account currency produces payments that fail or reconcile poorly. Record the supported list in your runbook and recheck it when a gateway changes its terms or you add a new country.
Plan for disabled server scripts
Server Scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting, and Frappe Cloud public shared benches do not allow them. If your webhook handling depends on a Server Script, decide early whether you will enable it on self-managed benches, move the logic into a custom app, or use a dedicated server that permits it. Confirm this choice before the build starts, because it changes the review and deployment path.
Common payment integration failures and how to fix them
This table lists the failures teams most often hit when connecting ERPNext Payment Requests to a gateway, with the likely cause, the check to run and the fix for each. Read it as a triage sheet: start with the symptom your finance team sees, then work back to the webhook, currency or fee setting behind it.
| Failure | Likely cause | Check to run | Fix |
|---|---|---|---|
| Webhook events rejected | The gateway cannot reach the site's webhook endpoint, or the webhook secret saved in ERPNext does not match the one configured at the gateway | Review the gateway's delivery log for failed attempts and response codes, then confirm the public URL resolves and the secret matches exactly | Expose the endpoint over HTTPS on a reachable hostname, re-enter the secret in the gateway account settings and replay the failed events |
| Payment received but Payment Request still open | The payment event arrived but was not processed, often because the Payment Request was not linked to the gateway transaction or the event type was not handled | Compare the gateway payment ID with the Payment Gateway Account references and check the error log for failed processing | Correct the reference or event mapping, reprocess the event and then reconcile the Payment Request manually if needed |
| Duplicate Payment Entries | The gateway retries a webhook it considers unacknowledged, and the handler creates a new Payment Entry each time | Search Payment Entries for repeated reference numbers and confirm whether the gateway shows one charge | Make the handler idempotent by checking for an existing entry before creating one, then cancel and reconcile the duplicates |
| Currency mismatch | The customer's invoice currency differs from the currency of the gateway account, or the gateway settles in a currency the account does not support | Compare the Sales Invoice currency, the Payment Request currency and the gateway account currency, and confirm the currencies the gateway supports for your account | Create a gateway account per supported currency, or align invoice currency with the settlement currency before requesting payment |
| Subscription renewals do not create invoices | The Payment Request was not marked as a subscription, the payment plan is missing, or the gateway-side subscription was cancelled | Check the subscription status in ERPNext and in the gateway dashboard, and confirm the payment plan is linked | Re-link the subscription to a valid payment plan, recreate the gateway subscription if it was cancelled and confirm the renewal event is processed |
| Settlement totals do not match bank lines | Gateway fees, refunds, disputes or payout timing were not mapped to expense or bank accounts, so the payout differs from the sum of invoices | Reconcile one payout against the gateway's settlement report, listing gross, fees and net amounts | Map fee and refund accounts in the gateway settings, then match the net payout to the bank line during reconciliation |
| Refunds not reflected in ERPNext | Refunds were issued in the gateway dashboard only, so no matching Payment Entry or credit note exists in ERPNext | Compare refund events in the gateway log with ERPNext records for the same invoice | Record refunds through the process your finance team agrees on, and confirm which events the integration handles automatically |
Questions buyers ask before hiring help with payment gateways
What drives the cost of an ERPNext payment gateway integration?
The main drivers are the number of gateways, the currencies and countries you accept, whether you need subscriptions, how much custom webhook handling you require, and how strict your reconciliation rules are. Each gateway adds its own account setup, test cases and finance review, so two gateways rarely cost twice as much as one, but they never cost nothing extra. Ask the partner to price each gateway, each currency rule and each custom handler as separate line items in the written scope. DeployOpen does not publish prices, so request a written scope and quote before comparing options.
How long does a payment gateway integration take?
Duration depends mostly on sandbox access and finance review, not on the code alone. Gateway sandbox accounts, test API keys and webhook testing can each take time to arrange, and your finance team needs to approve how payments map to bank and ledger accounts before go-live. Subscription logic, multi-currency rules and reconciliation edge cases such as refunds, partial captures and failed payouts extend the schedule. Confirm the expected timeline in the written scope, along with the dependencies on your side.
Can our hosting setup run custom payment webhook code?
Possibly not, and this check should come first. Server Scripts in Frappe are disabled by default from version 15 and must be enabled with the server_script_enabled setting. Frappe Cloud public shared benches do not allow them. If your hosting does not allow server code, custom webhook logic will need a custom app deployed on infrastructure you control. Confirm the hosting model before you agree on scope, because it changes both the build approach and the cost.
What do we need to provide before the work starts?
Plan to supply a merchant account with each gateway you want to use, sandbox and live API credentials handled through your secrets process, and a decision on which bank and ledger accounts receive gateway payouts. You also need sample invoices and Payment Requests that show the real cases, such as partial payments and refunds, and a public HTTPS endpoint that the gateway can reach for webhooks. Your team should also name a finance owner who can sign off on reconciliation rules.
Can an internal ERPNext team set up gateways without a partner?
Yes, for a single gateway with standard one-time payments, an experienced ERPNext administrator can often complete the setup using the vendor documentation. The Stripe and GoCardless integrations, for example, are documented in the ERPNext docs and include webhook secret configuration. The effort rises when you add several gateways, subscriptions, custom webhook handling or reconciliation rules that your auditors will review. Be honest with yourselves about who will own the setup after launch, because that person needs to understand both ERPNext and the gateway's API changes.
What happens to the integration after go-live?
Expect ongoing work for version upgrades, changes to gateway APIs and webhook formats, and new currencies or payment methods. ERPNext releases minor versions frequently, so the integration needs regression tests after each upgrade. Monitoring should cover failed webhooks, unmatched payments and reconciliation differences, with alerts sent to the finance and operations owners. Ask the partner whether support and upgrades are available as a retainer and what the written scope covers after launch.
Does DeployOpen handle the compliance side of card payments?
DeployOpen can help plan the architecture so that card data stays with the gateway, and can document the controls your assessor will ask about. DeployOpen does not issue audit reports, attestations or certifications, and independent auditors decide whether your payment setup meets the applicable requirements. Ask for the compliance scope in writing, including which controls are covered, which evidence is delivered and which parts remain your responsibility.
What should we ask for in a payment gateway quote?
Ask for a written scope that lists each gateway, each currency and country, the subscription and refund cases, the webhook design and the reconciliation rules. The quote should separate one-time build work from recurring support, state the sandbox and testing assumptions, and name what you must provide. Also ask how the partner handles hosting restrictions, upgrade testing and handover documentation. A clear scope makes it possible to compare offers fairly.
How DeployOpen works on this
DeployOpen plans, implements, tests, documents and supports ERPNext payment gateway integrations inside your own infrastructure. We start from the gateways you accept, the currencies and payment methods you need, and how each payment should land in your accounting, so the written scope reflects your actual money flows.
How we scope
- We list the gateways, accounts, currencies and payment methods you need before any configuration begins.
- We map each Payment Request type to the Sales Invoice, Payment Entry and bank ledger it should create.
- We confirm webhook endpoints, secrets storage and which environment (test or live) each gateway will use.
How we build
- We configure gateway accounts and Payment Gateway records in a staging ERPNext site before touching production.
- We test webhook delivery, signature validation, duplicate events and failed payments against sandbox credentials.
- We run reconciliation checks that compare gateway settlement reports with ERPNext bank and payment entries.
How we hand over
- We deliver a written runbook covering account setup, currency limits, webhook configuration and reconciliation steps.
- We document every custom script, secret and configuration key, with owners named for each item.
- We walk your finance and operations staff through a settlement close using the delivered procedure.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- We can review gateway API changes and ERPNext version upgrades that affect payment flows before they reach production.
