Odoo Integration: Track invoice payments

If you use Odoo to manage your business operations and accounting, you likely rely on its invoicing system to send and manage payments. However, if you’re collecting payments via mobile money or bank transfers, reconciling those payments manually can be a hassle.

With ClickPesa’s Order BillPay Control Numbers, you can simplify and automate payment tracking directly in Odoo. This article explains how to integrate ClickPesa into your Odoo invoicing workflow, so you know exactly when a customer has paid, without manually checking bank statements.

What Is an Order BillPay Control Number?

An Order BillPay Control Number is a unique payment reference that combines:

• Your Merchant BillPay-Namba (a 4-digit code assigned by ClickPesa)
• A unique Order Reference, such as an invoice number from Odoo

Formula:

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

Example:

• BillPay-Namba: 1122
• Odoo Invoice: INV20240332
• Control Number: 1122INV20240332

Customers use this control number when paying via mobile money or bank. ClickPesa then sends a webhook back to your system with the payment confirmation.

Step-by-Step: Integrating ClickPesa with Odoo

Step 1: Add the Control Number to Each Odoo Invoice

In your Odoo invoicing module:

1. Create or modify an existing invoice.
2. In a custom field (or the reference field), append the Order BillPay Control Number.
3. You can automate this by creating a custom Odoo field that concatenates your BillPay-Namba and the invoice number.

Example:

@api.depends('name')
def _compute_billpay_control_number(self):
    self.billpay_control_number = f"1122{self.name}"

Display this control number in:

• Printed or PDF invoices
• Emails or SMS reminders sent to customers

Step 2: Receive Payment Notifications via Webhook

ClickPesa supports webhooks that notify your system when a payment has been made using a control number.

You will need to:

1. Set up an endpoint in Odoo (using a controller) to receive webhook payloads.
2. Parse the payload to extract:
   • orderReference
   • controlNumber
   • amountPaid
   • status

Example route in Odoo:

@http.route('/clickpesa/webhook', type='json', auth='public')
def clickpesa_webhook(self, **kwargs):
    data = request.jsonrequest
    reference = data.get('orderReference')
    amount = data.get('amountPaid')
    status = data.get('status')

    invoice = request.env['account.move'].sudo().search([('name', '=', reference)], limit=1)
    if invoice and status == 'fulfilled':
        invoice.write({
            'payment_state': 'paid',
            'clickpesa_paid_amount': amount
        })
    return {'status': 'ok'}

Note: You can also store the control number and match against controlNumber if needed.

Step 3: Reflect Payment in the Invoice

Once payment is confirmed:

• The Odoo invoice is marked as Paid or Partially Paid
• A note or log entry can be added to the invoice history
• Optionally, you can trigger an email or SMS notification to confirm receipt to the customer

Optional: Automate Payment Matching for Partial Payments

Extend your webhook logic to handle:

• Overpayments
• Underpayments
• Partial installments

You can store the amount paid and update the amount_residual or use Odoo’s built-in partial reconciliation features.

Summary Workflow

1. Generate control numbers for each invoice in Odoo
2. Share control numbers with customers for payment
3. Set up a webhook to receive ClickPesa payment notifications
4. Match invoice by order reference
5. Update payment status in Odoo automatically

Final Thoughts

ClickPesa’s integration with Odoo via Order BillPay Control Numbers makes mobile money and bank transfer payments just as trackable and efficient as card or direct integrations. Whether you’re billing clients monthly, issuing ad-hoc invoices, or collecting donations, this setup ensures your finance team stays updated in real-time.

Need help building the webhook or custom field in Odoo? ClickPesa can support to get you up and running fast.