ERPNext Integration: Track Invoice Payments

ERPNext is a powerful, open-source ERP system used by growing businesses to manage everything from sales to accounting. If you collect payments via mobile money or direct bank transfers, reconciling them in ERPNext can be difficult without direct integration.

ClickPesa’s Order BillPay Control Number system makes this seamless by letting you assign a unique payment reference to each invoice, and automatically updating the invoice in ERPNext when payment is received. Here’s how to integrate it.

---

What Is an Order BillPay Control Number?

An Order BillPay Control Number is a dynamic number made up of:

• Your Merchant BillPay-Namba (assigned by ClickPesa)
• A unique Order Reference (such as the invoice number in ERPNext)

Formula:

Order BillPay Control Number = [BillPay-Namba] + [Invoice Name]

Example:

• BillPay-Namba: 1122
• ERPNext Invoice: ACC-INV-2024-0045
• Control Number: 1122ACC-INV-2024-0045

Customers use this number when paying. ClickPesa identifies the payment and sends a webhook to ERPNext.

Step-by-Step: Integrating ClickPesa with ERPNext

Step 1: Add Control Number Field to Sales Invoice

In ERPNext:

1. Go to Customize Form > Sales Invoice
2. Add a new Read-Only field:
   • Field Label: BillPay Control Number
   • Field Type: Data
   • Field Name: billpay_control_number
3. Add a custom script to auto-generate the control number:

frappe.ui.form.on('Sales Invoice', {
    validate: function(frm) {
        const billpayNamba = '1122';
        frm.set_value('billpay_control_number', billpayNamba + frm.doc.name);
    }
});

4. Show this control number in:
   • Printed invoice templates
   • Email templates or SMS notifications

Step 2: Set Up Webhook Endpoint in ERPNext

To automatically update payment status, create a custom endpoint in ERPNext:

1. In your custom app, create a Python file (e.g., clickpesa_webhook.py)

@frappe.whitelist(allow_guest=True)
def clickpesa_webhook():
    import json
    from frappe import request

    payload = json.loads(request.data)
    reference = payload.get('orderReference')
    amount = payload.get('amountPaid')
    status = payload.get('status')

    invoice = frappe.get_doc('Sales Invoice', reference)
    if invoice and status == 'fulfilled':
        invoice.db_set('outstanding_amount', 0)
        invoice.add_comment('Comment', text=f'Payment received via ClickPesa: {amount}')
        invoice.submit()
    return {"status": "ok"}

2. Add a route to hooks.py:

webhooks = [
    {"method": "POST", "path": "/api/method/yourapp.clickpesa_webhook.clickpesa_webhook"}
]

3. Register this endpoint with ClickPesa as your payment notification URL.

Step 3: Update Payment Status

Once the webhook is triggered:

• The invoice can be marked as paid (or partially paid, depending on amountPaid)
• A comment is added for visibility
• Optionally, notify your accounting team via email or alert

Optional Enhancements

• Store amountPaid in a custom field for future reference
• Match partial payments against outstanding_amount
• Extend logic to support Credit Notes or overpayments

Summary Workflow

1. Append BillPay Control Number to each ERPNext invoice
2. Share the number with customers via invoice, email, or SMS
3. Create a webhook in ERPNext to listen for ClickPesa payment notifications
4. Match the invoice by order reference and update payment status

Final Thoughts

By integrating ClickPesa with ERPNext, you remove manual reconciliation entirely. Mobile money and bank transfer payments become just as traceable as card payments or wire transfers. Whether you’re handling subscriptions, tuition, or service invoices, this setup ensures you stay accurate and efficient.

ClickPesa provides support and code samples to help you set up the webhook integration with ERPNext quickly and securely.