Security

This page covers how Frappe Mpesa Payments handles sensitive credentials, token management, and webhook security.

Credential Storage

All API credentials; Consumer Key, Consumer Secret, Initiator Password, and Security Credential are stored in the Mpesa Settings DocType.

Password fields in this DocType are stored as encrypted values using Frappe's built-in field encryption. They are never exposed in plain text through the UI or API responses.

The Mpesa Public Key Certificate DocType stores the Safaricom public keys used to encrypt the Initiator Password into the Security Credential required for B2C transactions. These certificates are Safaricom-issued and publicly available but are stored locally to avoid external requests at runtime.

Access Token Management

OAuth access tokens are generated by calling Safaricom's Daraja token endpoint using the Consumer Key and Consumer Secret. The generated token is stored within the Mpesa Settings record and reused for all subsequent API calls until it expires. When a token expires, the app automatically requests a new one before proceeding.

This approach avoids unnecessary token generation overhead and keeps API calls efficient.

Webhook Security

Safaricom's Daraja API delivers payment callbacks to a URL on your server. To ensure these callbacks are legitimate:

• Your site must use HTTPS. Safaricom does not deliver callbacks to non-HTTPS endpoints.
• The callback URL is derived from your site's domain and registered with Safaricom during C2B URL Registration.
• Incoming callback data is processed by the app's controller and recorded directly and no sensitive user credentials are passed through the callback.

Ensure your Nginx or reverse proxy configuration enforces HTTPS and does not expose the callback endpoints without TLS.

Initiator Password and Security Credential

For B2C disbursements and Transaction Status queries, the Daraja API requires a Security Credential the Initiator Password encrypted using Safaricom's public key certificate.

The app performs this encryption automatically at runtime using the certificate stored in the Mpesa Public Key Certificate DocType. The raw Initiator Password is never sent over the network; only the encrypted Security Credential is included in API requests.

Permissions

Access to Mpesa-related DocTypes should be controlled through Frappe's Role-Based Access Control system. Recommended practices:

• Restrict write access to Mpesa Settings to system administrators only.
• Grant read access to Mpesa C2B Payment Register to finance and accounts staff.
• Restrict submission and cancellation of B2C Payment Disbursement to authorized roles (e.g., Finance Manager).