Skip to main content

M-Pesa Daraja Payment Gateway

ECOSIRE M-Pesa Daraja connects submitted ERPNext Sales Invoices to Safaricom's Daraja API. It supports STK Push (Lipa na M-Pesa Online), C2B callbacks, a company-scoped transaction log, and automatic Payment Entry reconciliation.

The implementation treats the callback as untrusted input: a successful callback must match the pending request and its amount before ERPNext creates and submits the Payment Entry. A five-minute reconciliation job checks stale pending STK requests when a callback is delayed or lost.

note

B2C disbursements and refunds are a later phase. The current app does not send B2C payouts.

Before you start​

  • Install ecosire_mpesa_daraja, ERPNext v16, and ecosire_license_client.
  • Obtain a Daraja application, Consumer Key, Consumer Secret, and STK Passkey.
  • Obtain the Pay Bill or Buy Goods short code for production.
  • Provide a public HTTPS ERPNext URL that Safaricom can reach.
  • Activate the ECOSIRE licence before saving production settings.

Never paste credentials into notes, logs, source code, or support screenshots. The app stores them in Frappe Password fields and reads them through Frappe's encrypted credential API.

1. Configure M-Pesa Settings​

Open M-Pesa Settings as System Manager or M-Pesa Manager:

  1. Start with Environment = Sandbox.
  2. Enter the Business Short Code.
  3. Select:
    • CustomerPayBillOnline for a Pay Bill, or
    • CustomerBuyGoodsOnline for a Till.
  4. For a Till, set Party Short Code when required; a Pay Bill normally uses the Business Short Code.
  5. Enter the Consumer Key, Consumer Secret, and Lipa na M-Pesa Passkey.
  6. Enter the public HTTPS Callback Base URL without a trailing callback path; the app appends its endpoint.
  7. Set a short default account reference.
  8. Enable M-Pesa only after the sandbox connection test succeeds.

2. Request an STK payment​

  1. Open a submitted, unpaid Sales Invoice.
  2. Choose Request M-Pesa Payment.
  3. Confirm the customer's Kenyan mobile number and the amount.
  4. Ask the customer to approve the prompt on their handset.

The app creates a read-only Mpesa Transaction in Pending state. On a verified success callback it records the M-Pesa receipt, marks the transaction Success, and links the submitted Payment Entry reconciled to the invoice.

3. Review and reconcile​

Use M-Pesa Transaction to audit:

  • status and environment;
  • checkout and merchant request identifiers;
  • M-Pesa receipt number;
  • phone, amount, company, and originating document;
  • linked Payment Entry; and
  • request/callback payloads for authorised troubleshooting.

Transaction visibility is company-scoped. Accounts Manager and M-Pesa Manager have read/report access; settings and credential access remain restricted.

Pending STK requests are checked every five minutes. Investigate repeated timeouts rather than creating a manual Payment Entry immediately, because a late callback may still arrive.

Production cutover​

  1. Complete Safaricom's Daraja go-live process.
  2. Replace sandbox credentials with production credentials.
  3. Set Environment = Production.
  4. Verify the public HTTPS callback URL from outside the ERPNext network.
  5. Make one controlled low-value payment.
  6. Confirm exactly one successful Mpesa Transaction and one reconciled Payment Entry against the correct Sales Invoice.
  7. Confirm no secret value appears in application or proxy logs.

Troubleshooting​

SymptomCheck
No prompt reaches the phoneNumber format, enabled setting, credentials, short code, and environment
Transaction remains PendingPublic callback reachability; wait for the scheduled status query
Callback fails validationRequest identifier and amount must match the pending transaction
Payment Entry is not createdInspect Result Code/Description and the originating invoice state
Duplicate callback arrivesThe existing transaction should remain the single reconciliation record
Last updated on