Setting Up M-PESA as a Payment Method

Part 1: Enabling M-PESA

1. From the main menu, navigate to “Payment Methods”, from the account “Settings“.
2. Locate the M-PESA card in the list.
3. Toggle M-PESA ON — the credentials form opens immediately in the same drawer to complete the setup.

M-PESA is not considered active and will not appear on invoices until credentials are saved successfully. If you close the drawer before saving, the M-PESA card shows a “Configuration required” warning badge. Click the settings link on the card to return and complete the setup.

Part 2: Configuring Daraja Credentials (Initial Setup)

Once the credentials drawer is open, fill in the following fields — all fields are required:

• Environment (Required): Select Production for live transactions or Sandbox for testing. Defaults to Production on first load.
  • Production uses the base URL: https://api.safaricom.co.ke
  • Sandbox uses the base URL: https://sandbox.safaricom.co.ke
• Consumer Key (Required): Found in the Daraja portal under My Apps.
• Consumer Secret (Required): Found in the Daraja portal under My Apps.
• Business Shortcode (Required): Your Paybill or Till number registered with Safaricom.
• Passkey (Required): Sent by Safaricom via email after your app is approved for production.

Testing the connection before saving:

Click “Test Connection” to verify your credentials against the Safaricom OAuth endpoint using the values currently entered (not yet saved):

• Success: “Connection successful.”
• Failure: “Connection failed. Please check your credentials and try again.”

Click “Save” — on successful save you are redirected to the Payment Methods page and the message appears: “M-PESA settings saved successfully.” M-PESA is now active and available as a payment option on invoices.

Part 3: Updating Credentials After Setup

1. From the Payment Methods page, click the gear icon on the M-PESA card.
2. The settings page opens displaying your saved credentials:
   • Consumer Key: Shown in full.
   • Consumer Secret: Masked as ••••••••[last 4 characters] — shown in a disabled field.
   • Business Shortcode: Shown in full.
   • Passkey: Masked as ••••••••[last 4 characters] — shown in a disabled field.
   • Environment: Shown as the current selection.
3. Click on any masked field to enable it for editing.
4. Modify the fields you want to update.
5. Click “Test Connection” if needed to verify the new credentials before saving.
6. Click “Save” — the message appears: “M-PESA settings updated successfully.” You remain on the settings page.

Updating credentials only affects future payments. All historical M-PESA payment records remain unchanged.

Part 4: Disabling M-PESA

1. From the Payment Methods page, toggle M-PESA OFF.
2. A confirmation dialog appears — confirm to proceed.
3. M-PESA is removed from all invoice payment options going forward. The message appears: “M-PESA disabled successfully.”

All historical M-PESA payments remain intact and are not affected by disabling.

Security Notes

• Consumer Key, Consumer Secret, and Passkey are encrypted in the database and never exposed in logs, API responses, or anywhere on the frontend.
• Only the last 4 characters of masked fields are stored for display purposes.
• The settings page is restricted to users with the “Edit Payment Options” permission. Accessing it without this permission shows: “You do not have permission to access this page.”