A successful M-PESA transaction is not enough if the business cannot identify what it paid
Recurring merchants need a deterministic path from provider transaction to customer and billing period. Otherwise finance ends up matching by amount, phone number or screenshots after the fact.
Start with a merchant-owned invoice ID
Create the invoice before payment and give it a stable internal ID. The M-PESA transaction reference identifies the payment event; the invoice ID identifies the business obligation.
Keep both.
Use the PayBill account/reference field deliberately
Safaricom's C2B confirmation payload includes BillRefNumber, which carries the account/reference supplied with the PayBill payment.
For a recurring business, that reference can map to a member number, student admission number, tenant account or invoice reference. Choose a format that is stable, short enough for the customer to enter correctly and unambiguous inside your system.
Use C2B validation where it fits the merchant flow
Daraja C2B supports a ValidationURL and ConfirmationURL. When validation is enabled for the merchant flow, the business can check the incoming payment request before accepting it.
A practical validation rule is to reject an account reference that does not map to a valid customer/account rather than accept money that finance cannot identify later.
Validation policy must be designed carefully. A reference can be valid while the amount differs from the current invoice, especially for merchants that allow partial payments or account-level balances.
Match with several pieces of evidence
- BillRefNumber or merchant account reference.
- Internal invoice/account ID.
- TransID / provider transaction reference.
- TransAmount.
- BusinessShortCode.
- Transaction time.
- Payer identifier where available and lawful to use.
Amount alone is weak evidence because several customers can owe the same amount.
A matching hierarchy
- Direct invoice or attempt reference match.
- Known account/member reference match through BillRefNumber.
- Provider transaction reference already attached to an attempt.
- High-confidence multi-field heuristic.
- Human review.
The lower the confidence, the more visible the match should be to operations.
Wrong or missing references belong in an exception queue
If money arrives with a typo, missing account number or ambiguous reference, do not guess.
Show staff the transaction reference, amount, timestamp, available payer details and candidate accounts. Once staff resolve the match, preserve who made the decision and when.
Partial payments need an explicit policy
Some schools, property businesses and service merchants accept partial payment. Others require the full invoice amount.
The matching system should know the merchant policy. Do not infer the commercial rule from the transaction amount.
Matching should stop collection immediately
Once the invoice is satisfied, reminder and retry jobs should be cancelled even if downstream settlement reconciliation is still open.
That is why payment matching affects customer experience as much as finance operations.
Sources
- Safaricom Daraja Customer to Business API: https://developer.safaricom.co.ke/apis/CustomerToBusiness
- Safaricom Daraja API catalogue: https://developer.safaricom.co.ke/apis
