Skip to main content

Connect your own M-Pesa account

Open Settings → Payment Methods → M-Pesa (/admin/settings?tab=payments&provider=mpesa). “M-Pesa-ready” means NuSaaS has a connector; it does not supply a merchant account, activate your shortcode or confirm a payment.

Configure the provider​

  1. Enable your workspace's M-Pesa module and use an account with the required payment/settings permission.
  2. Obtain your own Safaricom Daraja application credentials and the appropriate shortcode/passkey. Select Sandbox for testing or Production only for your approved live account. Keep the credentials and environment consistent.
  3. Enter the consumer key, consumer secret, shortcode, passkey and account type (Paybill or Till) in the ERP form. Save settings. Enter optional initiator credentials only if you use operations that require them.
  4. Use Test connection. A successful credentials check is not proof that a phone prompt or payment callback works end to end.
  5. Enable M-Pesa in the payment-method overview. Configure each relevant sales channel too: POS and the delivery/public-checkout payment selection are separate.

Provider secrets are saved server-side for the business. Do not add them to VITE_*, the installer command, a public repository or a shared environment file. Preserve your server's APP_KEY to keep encrypted credentials usable.

Make callbacks reachable​

Use your public HTTPS API origin, not the frontend hostname, localhost or a Docker service name. The application generates callback addresses from its configured API URL:

https://api.example.com/api/payments/mobile/callback
https://api.example.com/api/payments/mobile/c2b/YOUR-WORKSPACE-SLUG/validation
https://api.example.com/api/payments/mobile/c2b/YOUR-WORKSPACE-SLUG/confirmation

Use the addresses generated for your business. Choose Register C2B URLs when configuring direct Paybill/Till notifications; this contacts Safaricom. STK Push has its own callback flow. Do not register another business's callback URL.

Your proxy/Tunnel must forward callbacks without a browser login or interactive challenge. Preserve application callback validation and source restrictions; do not disable them as a workaround. Check server time, HTTPS, the saved API origin and proxy configuration if notifications do not arrive.

Test the complete payment flow​

In sandbox, initiate an STK request through the intended POS or checkout channel. Inspect the transaction record and provider outcome. In production, an authorized small real transaction is a separate operator acceptance step. Confirm the final payment, provider reference, sale balance and accounting record agree before issuing a paid receipt. An accepted STK request, pending status or customer's SMS alone does not establish a completed payment in the ERP.

If M-Pesa is missing at checkout, check module access, saved provider readiness, the payment-method toggle and that channel's allowed payment methods. If a sale exists but initiation failed, retry payment on the same order, rather than creating another order. For delayed or uncertain outcomes, inspect/reconcile the existing transaction before initiating another request.

Payment success and KRA fiscal acceptance are separate. See KRA eTIMS setup for fiscal receipts and QR codes, and M-Pesa payment operations for cashier workflows.