3.1 DocTypes Reference
DocTypes Reference
This page describes all DocTypes introduced by the Frappe Mpesa Payments application. Use it as a technical reference when configuring the app, writing customizations, or troubleshooting issues.
Mpesa Settings
Mpesa Settings DocType
Purpose: Central configuration record for Daraja API credentials. One record is created per API type.
| Field | Description |
|---|---|
| API Type | Mpesa Express, C2B, or B2C |
| Consumer Key | API authentication key from Safaricom |
| Consumer Secret | Paired secret for API authentication |
| Business Shortcode | Your Paybill or Till number |
| Online PassKey | Used for Mpesa Express STK Push only |
| Till Number | Used for C2B Buy Goods payments |
| Initiator Name | API Operator username from M-Pesa Org Portal |
| Initiator Password | Password for the Initiator. Encrypted to generate Security Credential. |
| Security Credential | Encrypted credential for B2C transactions |
| Auto Reconcile C2B Payments | If enabled, auto-matches incoming C2B payments to invoices on submission |
Notes:
- Access tokens are auto-generated and cached in this record.
- Tokens are reused until expiry, then refreshed automatically.
Mpesa C2B Payment Register URL
C2B Payment Register
Purpose: Registers your server's callback URLs with Safaricom for C2B payment notifications. Must be completed before C2B payments can be received.
| Field | Description |
|---|---|
| Mpesa Settings | Links to the C2B Mpesa Settings record |
| Company | The company receiving C2B payments |
| Mode of Payment | Mode of Payment linked to C2B |
| Register Status | Reflects the result of URL registration (Success, Failed, Pending) |
Notes:
- Registration sends a request to Daraja and stores the result in Register Status.
- If Status is not Success, C2B callbacks will not be received.
Mpesa C2B Payment Register
C2B Payment Register
Purpose: Records individual incoming C2B payments received via Safaricom callbacks. Each record corresponds to one M-Pesa transaction.
| Field | Description |
|---|---|
| Full Name | Customer's name from the M-Pesa transaction |
| Transaction Type | Pay Bill or Buy Goods |
| Trans ID | Unique M-Pesa receipt number |
| Trans Time | Timestamp of the transaction |
| Trans Amount | Amount paid |
| Business Short Code | Shortcode that received the payment |
| Bill Ref Number | Account number entered by the customer |
| Invoice Number | Matched invoice, if found |
| Org Account Balance | Business account balance at time of transaction |
| Third Party Trans ID | Third-party integration identifier, if applicable |
| Posting Date and Time | When the record was created in ERPNext |
| Company | The receiving company |
| Customer | Matched customer record, if found |
| Mode of Payment | Payment mode used |
| Currency | Transaction currency |
Notes:
- Bill Ref Number is matched against Sales Invoice numbers and Customer names/numbers for smart linking.
- Draft records can be reconciled manually via the Mpesa Payment Reconciliation tool.
Mpesa Public Key Certificate
Public Key Certificate
Purpose: Stores Safaricom's public key certificates used to encrypt the Initiator Password into the Security Credential for B2C transactions.
| Field | Description |
|---|---|
| Sandbox Certificate | Certificate for the Daraja sandbox environment |
| Production Certificate | Certificate for live production transactions |
Notes:
- This is a Single DocType: there is only one record in the system.
- Certificates are available from the Safaricom Developer Portal.
- Must be populated before B2C disbursements can succeed.
B2C Payment Disbursement
Purpose: Manages outgoing payments from the business to employees, suppliers, or other parties via M-Pesa B2C.
Key fields include Party Type, Mode of Payment, Account Paid From, Account Paid To, and a References child table containing individual payment lines with mobile numbers and allocated amounts.
Status Values:
| Status | Description |
|---|---|
| Not Initiated | No payment attempts have been made |
| Paid | All references paid successfully |
| Partly Paid | Some references succeeded, others failed |
| Failed | All references failed |
Mpesa Payment Reconciliation
Payment Reconciliation
Purpose: A utility DocType used to manually match draft C2B payment records to outstanding customer invoices.
Contains two child tables:
- Mpesa Payments: Draft entries from the C2B Payment Register.
- Invoices: Outstanding Sales Invoices for the selected customer.
Payment Gateway
Payment Gateway
Purpose: Links Mpesa Settings to ERPNext's payment gateway infrastructure, enabling STK Push to be triggered from the Webshop (E-Commerce) checkout flow.
| Field | Description |
|---|---|
| Gateway Settings | The associated Mpesa Settings record |
| Gateway Controller | Manages routing and processing of payments |