How the ERPNext M-Pesa integration works at the point of sale
A retailer or service business that takes M-Pesa at the counter needs the payment request to start in the ERPNext Point of Sale, then return a confirmed payment that is recorded against the sale. The ERPNext M-Pesa integration works only with the Point of Sale and not with the shopping cart, so it does not cover online checkout on a website. If your revenue depends on web orders paid through M-Pesa, plan that flow separately before you commit to this design. The integration sits between the M-Pesa application and ERPNext, and it is configured under Integrations > Payments > M-Pesa Settings. Confirm the current scope and the exact field names with the ERPNext M-Pesa documentation before you build, since the vendor's documentation is the authority on what the screen accepts.
Before you open M-Pesa Settings, decide which Safaricom API product and environment you are integrating against, who holds the live API credentials, and where those credentials will be stored. Live credentials should be requested by an account holder who is authorized to bind the business to the M-Pesa API, and the reader should confirm the onboarding steps and any fees with Safaricom directly. Decide which ERPNext company, cash or bank account and Mode of Payment will receive the funds, because the payment entries created at the counter must reconcile to the correct ledger. Also decide which cashiers may take M-Pesa payments and which roles can change the settings, since those are controlled through ERPNext roles and permissions.
Plan the test path before any live transaction. Run the flow on a non-production site with test credentials, record a sale at the Point of Sale, complete a payment, and check that the resulting payment entry lands in the intended account. Then confirm what happens when a customer cancels a prompt, when a payment times out, and when the network drops between ERPNext and the M-Pesa application. These failure paths decide how cashiers reconcile the till at the end of a shift, so document who resolves an unmatched payment and how it is escalated.
What you need before configuring M-Pesa in ERPNext
The M-Pesa connector sits on top of a working ERPNext point of sale, so most delays come from gaps in the base setup rather than the payment settings themselves. The cards below cover the platform, hosting, provider credentials and POS accounts that need to be settled before you open M-Pesa Settings.
A supported ERPNext version
Confirm that your ERPNext and Frappe Framework version is on the supported list before you build anything. Frappe's support versions page lists which releases are still maintained, and the policy ties vendor warranty coverage to a listed version. Check the release you plan to deploy against the page on the day you start, because a version that is near end of life may force an upgrade before go-live. Ask your implementer which version they will pin.
A hosting option for the site
Choose where the site runs: Frappe Cloud, Docker Compose or a bench installation on Linux. The choice affects who patches the platform, how background jobs and the scheduler run, and whether you can install custom apps. Confirm that your hosting option lets you install the Payments app and expose the M-Pesa callback endpoint over HTTPS. Shared hosting plans may restrict the server-side features you need.
Live M-Pesa API credentials
Obtain production credentials from your M-Pesa provider or Safaricom developer account before testing against real payments. Sandbox keys are useful for rehearsal but will not move money, so plan a separate pass with live keys once the till or paybill details are confirmed. Ask the provider which product line your business is enrolled in, who holds the credentials, and how they are rotated. Record the exact credential names from the ERPNext M-Pesa documentation.
Payments app and gateway account
The M-Pesa connector is delivered through the Payments app, so that app must be installed on the same site and version as ERPNext. Create the payment gateway record and link it to a bank or cash account in your chart of accounts. Without that link, incoming payments have nowhere to post in the ledger. Confirm the currency your gateway account uses, since M-Pesa transactions are denominated in Kenyan shillings.
POS profile and payment accounts
Set up the POS Profile with the warehouse, price list, currency and payment modes that cashiers will use. Map the M-Pesa payment mode to the gateway account so that a POS invoice records the payment against the correct ledger. Test the mapping with a small sample invoice before you train staff. Remember that the integration works only through the Point of Sale, so this profile is the path every M-Pesa sale must take.
HTTPS callback URLs
M-Pesa notifies ERPNext of payment results through callback URLs that must be reachable over HTTPS from the public internet. Decide the site domain and certificate before configuration, and confirm the exact callback path, port and allowed IP ranges with your provider and the ERPNext M-Pesa documentation. Firewalls, reverse proxies and load balancers often block these requests during first tests, so involve your network team early.
Configuring M-Pesa Settings and testing a POS sale
This sequence takes an ERPNext site from M-Pesa API credentials to a tested point of sale payment, with each step closed by a check that confirms the payment request, the payment entry and the ledger postings. It is written for the team that will configure the integration and the finance reviewer who signs off on it.
Obtain live M-Pesa API credentials
The site owner or finance lead requests API credentials from Safaricom's M-Pesa developer and business channels for the organization's account, and confirms with the account holder which shortcode, environment and callback addresses apply. Keep sandbox and live credentials separate so that a test sale cannot post to a live account. Done means the team holds a named set of live credentials stored in a secure location, and the account holder has confirmed which of them belong to production. Confirm the exact fields and onboarding steps with M-Pesa directly, because the provider controls them and they can change.
Enter credentials in M-Pesa Settings
In ERPNext, go to Integrations > Payments and open M-Pesa Settings, then enter the credentials and environment values the provider issued. Save the record and confirm that the connection fields show the expected environment, with no values pasted into shared chat or tickets. Check the callback and validation addresses against the site's public URL, since a mismatch will cause payment confirmations to fail silently. Done means the settings record saves without errors and the team has documented who can edit it.
Link the M-Pesa mode of payment to a POS profile
Create or select the Mode of Payment for M-Pesa, then map it to a receivable account in the POS Profile that the cashiers use. The mapping decides where the money lands in the ledger, so the finance lead should agree the account with the accountant before go-live. Confirm that the POS Profile lists M-Pesa among its payment methods and that the account type matches the bank or clearing account used for M-Pesa receipts. Done means a POS session on that profile offers M-Pesa as a payment option.
Run a small test sale in a test environment
Using a test site or a test POS profile that does not post to live accounts, create a small POS invoice with one item and select M-Pesa as the payment method. Trigger the payment request, complete it on a test phone number that the provider allows for testing, and watch the request status in the POS and in the integration logs. Repeat with one failed or cancelled payment to see how ERPNext records it. Done means a successful test payment request appears with a status that matches the test outcome, and the failed case leaves no false payment entry.
Confirm the payment entry and reconciliation
After the test sale completes, open the resulting Payment Entry and the POS Invoice, and check that the amount, the mode of payment and the reference from M-Pesa match the test transaction. Then open the General Ledger for the receivable and bank or clearing accounts to confirm the debit and credit postings are correct. Mark the entry as reconciled against the test statement or provider report so the finance team knows the trail is complete. Done means the team can trace one test sale from the POS invoice to the payment entry and to the ledger, with no unexplained difference.
Repeat the test on live credentials with a limited pilot
Once the test trail is clean, switch the M-Pesa Settings to live credentials on the production site and run one small real sale on a controlled POS profile, under supervision of the finance lead. Compare the live payment entry and ledger postings with the test results before opening the profile to all cashiers. Done means the first live sale reconciles to the M-Pesa statement and the team has signed off in writing, which is the point at which the integration is ready for normal use.
Record the configuration and the sign-off
Document the M-Pesa Settings fields in use, the mode of payment and account mapping, the POS profiles affected, the test cases and their results, and the names of the people who approved go-live. Store the record with the site's configuration documentation and set a review point for credentials and callback addresses. Done means someone who was not part of the setup could repeat the configuration and understand where each payment lands. Keep in mind that the integration only covers the point of sale, so online cart payments need a separate plan.
Why the POS-only limit changes your sales channel plan
The most important planning fact is that the ERPNext M-Pesa integration works only with the Point of Sale and not with the shopping cart. An M-Pesa payment taken at the counter through POS can be recorded against the sale, but a customer who places an order on your webshop cannot choose M-Pesa through this path. If your business sells both over the counter and online, treat these as two separate payment channels from the start, not as one setting you extend later. Write down, for each channel, which payment methods customers can actually use and which ones your staff or your reconciliation process must handle manually.
For online checkout, plan a second payment method now. That may be a card or wallet gateway from the Payments app family, or another gateway your team has already approved, and it needs its own gateway account, currency settings, webhook handling and reconciliation rules. Decide before build which accounts receive online settlements and how they match to the bank ledger, because mixing counter M-Pesa receipts and online gateway receipts in one account is a common source of reconciliation work. Also decide what the storefront shows customers at checkout, so that no one is promised M-Pesa on the webshop when it is not available.
Before you promise M-Pesa on every channel, confirm three things in writing. First, check the current ERPNext M-Pesa documentation for the exact scope and any changes in your version. Second, ask your Safaricom or M-Pesa API contact whether the credentials and product you hold cover the transaction types you need at each channel. Third, ask us to include a test in the scope that shows a POS sale and an online order side by side, so the finance team sees how each one lands in accounting. Ask for these confirmations in your quote, since they determine whether the online channel needs a second gateway.
Mapping M-Pesa payments to ERPNext accounts and documents
This table maps each M-Pesa outcome to the ERPNext document it creates or updates, along with the account and mode-of-payment settings the team must confirm. Read it as a checklist to verify against the release you run, because the exact document chain depends on how your POS profile and M-Pesa Settings are configured. The main takeaway is that the mode of payment and the receiving account decide where money lands, so they should be set and tested before any live transaction.
| Outcome | ERPNext document affected | Fields to set and confirm |
|---|---|---|
| Successful POS payment | POS Invoice, with a linked Payment Entry or payment on the invoice | Mode of Payment set to the M-Pesa mode, default account for that mode, and POS Profile payment methods |
| Successful payment, receiving account | Bank or cash account ledger entry created from the payment | Account type (bank or cash) and the account linked to the M-Pesa mode of payment |
| Failed or cancelled STK request | No invoice payment recorded; POS Invoice stays unpaid or unsubmitted | Confirm the POS workflow leaves the invoice open and that no partial payment is posted |
| Request timed out or unconfirmed | Invoice remains open pending reconciliation against the M-Pesa statement | Confirm how your team matches pending requests to M-Pesa transaction references |
| Refund | Credit Note or reversing Payment Entry against the original invoice | Confirm the refund route and the account debited, and test it on a non-production site |
| Settlement to bank | Bank Transaction matched to the M-Pesa receiving account during reconciliation | Bank account in ERPNext matches the account M-Pesa settles into |
| Shopping cart orders | Not applicable: the integration works only with POS | Route online orders through a supported gateway instead, and confirm this before design |
Protecting M-Pesa credentials and POS transactions
M-Pesa payments at the ERPNext point of sale touch live API credentials, configuration screens and the cashiers who trigger payments. The cards below cover the controls that connect those three areas, and the points to confirm with Safaricom and your compliance team before go-live.
Live credentials in M-Pesa Settings
The M-Pesa Settings form under Integrations > Payments holds the API values that let ERPNext initiate payment requests. Treat these values as secrets: do not paste them into shared tickets, chat threads or screenshots, and confirm who at your organization holds the Safaricom daily portal access needed to issue or rotate them. Ask your Safaricom representative how credentials are reissued if one is exposed, and plan the cutover so the old values stop working.
Separate test and live configuration
Keep a sandbox M-Pesa configuration on a non-production ERPNext site and reserve the live configuration for production only. Mixing them is the most common way a test charge reaches a real customer or a live shortcode receives a demo transaction. Document which site and which credential set each environment uses, and confirm with Safaricom how test access is provisioned for your account.
Restricting who edits payment settings
Changing the M-Pesa Settings record, or the gateway account it points to, changes where money is routed. Limit edit rights on the Payment Gateway and M-Pesa Settings DocTypes to a small administrator role through ERPNext role permissions, and remove those rights from general accounting and sales roles. Review the role matrix after every upgrade or app install, because permission changes can arrive with new DocTypes.
HTTPS on callback endpoints
M-Pesa responds to your site with payment result callbacks, so the public address ERPNext exposes must use HTTPS with a valid certificate. Confirm the exact callback URL that the integration registers, check that your reverse proxy forwards it to the correct site, and make sure plain HTTP redirects cannot break the callback path. Test with a payment on the sandbox before relying on it at the till.
Audit trail for settings changes
Settings changes are only useful as evidence when someone can see who changed what and when. Enable Frappe's version tracking on the M-Pesa Settings and Payment Gateway records, and export the Version log on a schedule to a system your administrators do not control. Compare the log with change tickets during access reviews, and ask your provider how payment result records are retained.
Cashier access at the POS
Cashiers should be able to take M-Pesa payments at the Point of Sale without being able to change the payment configuration, refund outside a documented process, or alter completed invoices. Map the POS user role to only the actions the till needs, set a POS Profile per till, and review which cashiers can apply discounts or cancel invoices. Confirm with your compliance team whether the till workflow falls within any payment-card or cash-handling control set you follow, since that determines the evidence you must keep.
Common M-Pesa POS failures and how to fix them
This table lists the failures most likely to block M-Pesa payments at the ERPNext point of sale, with the usual cause, the fix and where to look first. Read each row against what you see on the POS screen, then check the logs or provider console only where the row tells you to.
| Failure | Likely cause | Fix and where to check |
|---|---|---|
| Credentials rejected | Sandbox keys entered in a live setup, or keys copied with extra spaces or a truncated value | Confirm you are using live API credentials from your Safaricom developer account, re-enter them in M-Pesa Settings and save. Check the error response in the Error Log before changing anything else. |
| Callbacks not reaching the site | Site not reachable over public HTTPS, firewall or proxy blocking inbound requests, or a callback URL that does not match the site | Confirm the site's domain resolves publicly with a valid certificate and that the callback path reaches ERPNext. Test from outside your network. Check web server access logs for the incoming request. |
| Payment succeeds at M-Pesa but not in ERPNext | Callback received but rejected, document not matched to the request, or the background worker not running | Check the Error Log and the background job queue for failed jobs. Confirm the Payment Request or POS reference matches the one sent. Check the provider console to confirm the transaction completed. |
| Mode of payment missing from POS profile | M-Pesa mode of payment not added to the POS profile, or not linked to a company account | Open the POS Profile, add the M-Pesa mode of payment in the payments table and link it to the correct account. Reload the POS screen after saving. |
| Currency or account mismatch | Mode of payment linked to an account in a different currency or company than the POS invoice | Compare the account currency with the POS invoice currency and company. Correct the account link in the mode of payment or the POS Profile, then retest with a small transaction. |
| Payment appears to fail on the till | Shopping cart expected, or the sale was not created through the point of sale | Remember the integration works only with POS, not the shopping cart. Confirm the sale was started from the POS screen. Check the M-Pesa Settings to confirm the integration is enabled. |
| Duplicate or missing entries after retries | Cashier retried a payment that had already completed, or a callback was replayed | Search Payment Entries and POS Invoices by M-Pesa reference before re-collecting. Check the provider console for the transaction status. Reconcile with your bank feed before closing the day. |
Questions buyers ask about the ERPNext M-Pesa POS integration
Can we set up the ERPNext M-Pesa integration ourselves?
Yes, if your team already runs ERPNext and can work through the Integrations > Payments > M-Pesa Settings screen and the provider onboarding steps. The configuration itself is short, but the time goes into obtaining live API credentials from the M-Pesa provider, testing with real transactions, and confirming that receipts reconcile to the right accounts. Teams without a Frappe developer or someone who can read payment logs usually find the test cycle the hardest part. Start with the ERPNext M-Pesa documentation and confirm each step against your own environment and provider account.
What drives the effort on an M-Pesa POS integration?
The effort follows the shape of your sales operation rather than the connector itself. The main drivers are:
- The number of POS terminals or cashier stations that will accept M-Pesa payments
- The number of M-Pesa accounts, paybill or till arrangements, and the mapping of each to ERPNext payment accounts
- Whether you transact in more than one currency or run several companies on one site
- How many test cycles you need before go-live and how many staff roles must sign off
- Provider onboarding, which depends on the M-Pesa provider and is outside ERPNext
Ask any partner to list each of these in the written scope.
How long does M-Pesa provider approval take?
The timeline depends on the M-Pesa provider and the documentation it requests, so no fixed duration applies here. Before you start, gather your business registration documents, the account or till details you plan to use, the people authorized to act for the business, and the contact details for technical sign-off. Ask your provider for its current onboarding steps and expected processing time in writing, and build that wait into your plan before any go-live date is set. Missing paperwork is the most common cause of delay.
Can customers pay with M-Pesa in the online shopping cart?
No. The ERPNext M-Pesa integration works only with the Point of Sale and not with the shopping cart, so online checkout cannot use it through this connector. If you need M-Pesa on a website, that is a separate scope that needs its own design, and you should confirm which payment gateway options your ERPNext version and provider support before committing to a plan. Treat online payments as a different project with its own testing and reconciliation.
What does a fixed-scope quote for this integration cover?
A fixed-scope quote follows from a written scope that lists what will be delivered before work starts. For this integration, expect the scope to name the POS terminals in use, the M-Pesa accounts and ERPNext payment accounts involved, the configuration in M-Pesa Settings, the test plan and test cycles, the staff training you need, and the handover documents. It should also state what you must provide, such as provider access and credentials, and what is excluded, such as online cart payments or changes to your provider contract. DeployOpen does not publish a price list, so ask for a quote tied to that written scope.
What should we check in our own environment before the build?
Confirm your ERPNext version and that it is on a supported release line, since the Frappe supported versions page lists the current end-of-life dates. Check that the POS module is configured with the items, price lists and warehouses you use in stores. Confirm who holds the live API credentials and how they will be stored, and make sure those secrets are not shared in email or chat. Finally, agree on a test environment and a way to replay failed payments, so reconciliation problems surface before cashiers depend on the flow.
What goes wrong most often with mobile money payments in ERPNext?
The most common problems are credentials that work in testing but are not live, callback or notification endpoints that are unreachable from the provider, and payment entries that do not match the accounts your finance team expects. Duplicate or delayed confirmations can also leave a sale open while the money has already arrived. Plan for a daily reconciliation between provider statements and ERPNext payment records, and assign an owner for failed or pending transactions from the first day of trading.
What DeployOpen confirms before quoting M-Pesa work
DeployOpen does not quote M-Pesa work until the scope is agreed in writing. The first things we confirm are the ERPNext version, the hosting model (Frappe Cloud, Docker Compose or a bench install on servers you control), the POS profiles that will take M-Pesa payments, and the accounts each profile posts to. We also ask which M-Pesa account details you can supply and who holds them, because the integration needs live API credentials that belong to your business. Version and hosting answers matter here: they decide which M-Pesa Settings screen and background job behavior you will be working with, and whether Server Scripts or custom apps are needed for any local adjustment. Confirm the points with your own team before you request a quote.
Once those answers are known, the written scope covers configuration of M-Pesa Settings under Integrations > Payments, linking the gateway account to the POS payment modes, and test sales run on a non-production site before any live till is touched. It also covers reconciliation checks, so that each test payment can be traced from the M-Pesa side to the Payment Entry and the bank ledger in ERPNext, and a handover session where your staff run through the cashier and supervisor steps. Each of these is a fixed deliverable with an agreed acceptance point, so you know what you receive before work starts.
Ongoing support is not part of the initial build. If you want DeployOpen to watch reconciliation, review ERPNext upgrades that touch the Payments app, or handle changes to POS profiles after go-live, that work is available as a retainer and is scoped separately. Ask us to state in the quote which items are one-time and which recur, and ask your M-Pesa contact to confirm the API access terms that apply to your business before the build starts.
How DeployOpen scopes and supports ERPNext payment integrations
DeployOpen plans, implements, customizes, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For ERPNext M-Pesa integration for point of sale payments, we start from a written scope that names the point of sale flows, the M-Pesa Settings configuration and the test and live credential steps before any build begins.
How we scope
- Confirm which point of sale flows will accept M-Pesa and that the shopping cart is excluded from the design
- Record the Integrations > Payments > M-Pesa Settings values, account mapping and owner for each credential
- Agree the scope, deliverables and timeline in writing before work starts, as most engagements are fixed-scope
How we build
- Configure M-Pesa Settings and the linked payment accounts in a staging ERPNext site first
- Test point of sale payment requests end to end, including failed and cancelled payments, before any live cutover
- Keep credentials out of source control and store them in your chosen secrets process within your infrastructure
How we hand over
- Document the configuration, credential ownership, account mapping and the point of sale only limitation
- Provide a runbook for daily reconciliation of M-Pesa receipts against ERPNext payment entries
- Walk your finance and point of sale staff through cashier steps and the escalation path for failed payments
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after go-live
- Review the integration whenever ERPNext or the Payments app moves to a new minor or major release
- Confirm with your M-Pesa provider and your own environment before any change to live credentials
