Callback URLs

The addresses Safaricom and the banks post payment notifications to. Registered URLs never change; the M-Pesa ones are public, the bank ones are issued privately.

Who needs this page

Churches do not configure these by hand: registering the C2B URLs is a button in the portal (Paybill setup) and payment prompts carry their own result URL. This page is for Safaricom support conversations, partners and auditors.

M-Pesa (Safaricom Daraja)

C2B confirmation

POSThttps://uat-api.mychurch.co.ke/api/v1/confirmSafaricom

The ConfirmationURL registered for every church paybill. Safaricom posts TransID, TransAmount, BusinessShortCode, BillRefNumber, MSISDN (a SHA-256 hash of the payer's number) and the payer's names. MyChurch stores the claim, answers at once and verifies before crediting (Payment verification).

Example notification body

{
  "TransactionType": "Pay Bill",
  "TransID": "RKT4XYZ123",
  "TransTime": "20261005101240",
  "TransAmount": "1000.00",
  "BusinessShortCode": "123456",
  "BillRefNumber": "tithe",
  "OrgAccountBalance": "",
  "MSISDN": "2f1c...e9a4",
  "FirstName": "JANE"
}

C2B validation

POSThttps://uat-api.mychurch.co.ke/api/v1/callbackSafaricom

The ValidationURL. MyChurch accepts every payment here and answers {"ResultCode": 0, "ResultDesc": "Accepted"}: a payment to an unknown account number is better reviewed than refused.

Payment prompt (STK) result

POSThttps://uat-api.mychurch.co.ke/api/v1/callback-pushSafaricom

The CallBackURL sent with every payment prompt. Matched by CheckoutRequestID; answered {"ResultCode": 0, "ResultDesc": "Accepted"}.

Transaction Status

POSThttps://uat-api.mychurch.co.ke/api/v1/transaction-check/resultSafaricom

POSThttps://uat-api.mychurch.co.ke/api/v1/transaction-check/timeoutSafaricom

The ResultURL and QueueTimeOutURL of the verification queries MyChurch makes. Parameters are read by name, not by position.

Pull API

POSThttps://uat-api.mychurch.co.ke/api/v1/transactions-pull/confirm/{church}Safaricom

POSThttps://uat-api.mychurch.co.ke/api/v1/transactions-pull/result/{paybill}Safaricom

Used where Safaricom's Pull API is enabled for a paybill, to fetch statement lines missed by the confirmation URL. Each line is treated as a claim and verified the same way.

The same paths under /api/v2

Every M-Pesa path above except the Pull API also answers under /api/v2/. Existing registrations use /api/v1/ and stay there.

New registrations: /webhooks

Registrations made after the move to the new platform may use these paths instead. They are answered by the same code as the frozen paths.

POSThttps://uat-api.mychurch.co.ke/webhooks/mpesa/c2b/confirmSafaricom

POSThttps://uat-api.mychurch.co.ke/webhooks/mpesa/c2b/validateSafaricom

POSThttps://uat-api.mychurch.co.ke/webhooks/mpesa/stk-resultSafaricom

POSThttps://uat-api.mychurch.co.ke/webhooks/mpesa/transaction-statusSafaricom

POSThttps://uat-api.mychurch.co.ke/webhooks/mpesa/transaction-status-timeoutSafaricom

Banks

Equity (payment prompt results and payment gateway notifications), KCB (payment prompt results and instant payment notifications) and Co-operative Bank post to callback URLs whose last path segment is a shared secret. Written out with that segment hidden, they look like:

POSThttps://uat-api.mychurch.co.ke/api/v1/kcb-callback/{secret}KCB

and likewise equity-stk-callback, equity-callback-pgw, kcb-ipn and coop-callback. The full URLs are given to each bank by MyChurch support and are never published. A request with a wrong segment answers 404 and is not processed. NCBA posts to /api/v1/ncba/confirm.

Treat a callback URL like a password

Do not paste bank callback URLs into tickets, chats or documents. If one may have leaked, tell [email protected]; callbacks are still checked against references MyChurch issued, so a leaked URL alone cannot credit money.

Answering rules

Callbacks are never rate limited.
Every body is stored as received (passwords and security credentials redacted) before anything else happens.
The answer is immediate and does not depend on whether the payment can be credited.