Wire up the payment rail

A Kenyan MFI without M-Pesa is a museum. This page walks the Daraja v2 wiring — OAuth credentials, STK push, C2B validation, B2C disbursement — plus the bank journal hookup that closes the loop.

Daraja credentials

Before you start, the MFI Treasury team must have:

• A Lipa Na M-Pesa Paybill or Till from Safaricom Business (apply at daraja.safaricom.co.ke or via your relationship manager).
• A Daraja app registered in the developer portal with Consumer Key and Consumer Secret.
• Both sandbox and production credentials — never test against production with live phones.
• The B2C initiator name and security credential (encrypted via Safaricom's public key).
• The C2B validation URL and confirmation URL whitelisted by Safaricom support.

Configure the Daraja provider in BridgeERP

Open MFI → Configuration → Mobile money providers → New:

# Settings captured
name: Bridge MFI — M-Pesa
code: MPESA_BRIDGE
provider: safaricom_daraja
environment: sandbox  # flip to production after UAT
paybill: 522522
consumer_key: <from portal>
consumer_secret: <from portal, encrypted at rest>
pass_key: <from portal — for STK push>
initiator_name: bridge_b2c
b2c_security_credential: <encrypted with Safaricom public key>
callback_url_validation: https://mfi.example.co.ke/mfi_mpesa/c2b/validation
callback_url_confirmation: https://mfi.example.co.ke/mfi_mpesa/c2b/confirmation
callback_url_stk: https://mfi.example.co.ke/mfi_mpesa/stk/callback
callback_url_b2c_result: https://mfi.example.co.ke/mfi_mpesa/b2c/result
callback_url_b2c_timeout: https://mfi.example.co.ke/mfi_mpesa/b2c/timeout

STK push (member-initiated repayment)

STK push prompts a member's phone to confirm a payment. Used for repayments and deposits triggered from the branch or from iBANK.

1. Member calls the branch or opens iBANK and chooses 'Pay loan'.
2. System looks up the outstanding installment and pre-fills the amount.
3. System sends an STK push to the member's phone (PUT /mpesa/stkpush/v1/processrequest).
4. Member sees the prompt, enters PIN, confirms.
5. Safaricom posts an STK callback to /mfi_mpesa/stk/callback.
6. System matches the callback to the original request via the CheckoutRequestID.
7. On success, the loan repayment is posted to the GL and the schedule advances.

C2B (paybill deposits)

C2B is for members who push payments themselves via the M-Pesa menu. The account reference must encode the loan number or savings account so the system can auto-allocate.

B2C (disbursement)

B2C pushes money from the MFI's paybill to a member's phone for loan disbursement. Use for loans up to KES 70,000 — above that, use bank transfer.

• Same-day limit per phone: KES 150,000 (Safaricom default; can be lifted).
• Per-transaction limit: KES 70,000 (Safaricom default).
• Fee: paid by the MFI; charged at Safaricom's published B2C tariff (~KES 75 for a KES 50K transfer).
• Settlement: T+0 to the member, T+1 to the MFI's settlement bank.
• Reconciliation: B2C Result callback must post within 60s or the system flags the transaction as pending_confirmation.

Bank rail (RTGS, EFT, PesaLink)

For disbursements above KES 70,000 and treasury sweeps, configure at least one bank API. The shipped connectors:

Most tenants enable PesaLink (instant, KES 80, up to KES 999,999 per leg) for mid-size disbursements and RTGS for anything above.

Go-live checklist

1. Sandbox STK push + C2B + B2C all succeed with test phone +254708374149.
2. Callback URLs whitelisted by Safaricom (email confirmation in hand).
3. Production credentials encrypted at rest (check mfi.mpesa.provider uses BridgeERP's vault).
4. Bank API connector tested with KES 100 transfer.
5. Cron mfi_mpesa_reconcile running every 15 minutes.
6. Two-person rule CASH_OUT extended to cover B2C above KES 100K.

Worked scenarios

Reference

Daraja v2 endpoints used

Common Safaricom result codes

Troubleshooting

See also

• Install
• Treasury
• Transactions
• Disbursement