Set up your paybill or till

Connect the church's own M-Pesa paybill or till so members' payments are received, verified and credited automatically. Most churches do this once, in the portal, in about fifteen minutes.

What you need from Safaricom

On the Safaricom Daraja portal (or from your Safaricom account manager), for the paybill or till the church owns:

Consumer key and consumer secret of a production Daraja app with the M-Pesa Express (STK), C2B and Transaction Status products.
Passkey for M-Pesa Express, if members will receive payment prompts.
Initiator name and initiator password of an API operator on the paybill. MyChurch uses them only to ask Safaricom whether a payment completed. Without them payments cannot be verified and will wait instead of being credited.
For a till: the till number and the store (head office) number it belongs to.

Step 1: add the paybill in the portal

Sign in to uat-app.mychurch.co.ke as a church admin, open Giving, Paybills and add the paybill. Credentials are encrypted as soon as they are saved and are never shown again in full; the portal shows only a hint of each.

The same is possible over the platform API:

POSThttps://uat-api.mychurch.co.ke/v1/paybillschurch:paybills:manage

Parameters

Field	Type	Required	Description
short_code	string	Yes	The paybill number, or for a till the store number Safaricom gave you. 5 to 8 digits.
is_till	boolean	No	true for a Buy Goods till.
till_number	string	No	The Buy Goods till number members pay. Required when is_till is true.
allow_stk_push	boolean	No	Whether members may receive payment prompts on this paybill. Needs pass_key.
settlement_account_uuid	uuid	No	The money account that receives the funds in the church's books.
consumer_key	string	Yes	Daraja app consumer key.
consumer_secret	string	Yes	Daraja app consumer secret.
pass_key	string	No	M-Pesa Express passkey (needed for payment prompts).
initiator	string	No	API operator (initiator) name, for verification.
initiator_password	string	No	API operator password. Send both initiator fields or neither.

# Paste your token once (it starts with mc_):
export MYCHURCH_TOKEN="mc_your_token_here"

curl -X POST https://uat-api.mychurch.co.ke/v1/paybills \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "short_code": "123456",
    "is_till": false,
    "allow_stk_push": true,
    "consumer_key": "your-consumer-key",
    "consumer_secret": "your-consumer-secret",
    "pass_key": "your-passkey",
    "initiator": "GRACEAPI",
    "initiator_password": "your-initiator-password"
  }'

Step 2: test the credentials

The Test button asks Safaricom for an access token with the stored key and secret, and warns if no initiator is stored.

POSThttps://uat-api.mychurch.co.ke/v1/paybills/{uuid}/testchurch:paybills:manage

Response

{
  "success": true,
  "data": { "ok": true, "description": "Safaricom accepted the consumer key and secret." }
}

Step 3: register the C2B URLs

Safaricom must know where to send payment notifications for your paybill. Press Register C2B URLs: MyChurch calls Daraja's register URL API with your credentials and these two URLs, and shows Safaricom's answer.

POSThttps://uat-api.mychurch.co.ke/v1/paybills/{uuid}/register-c2bchurch:paybills:manage

Response

{
  "success": true,
  "data": {
    "ok": true,
    "code": "0",
    "description": "Success",
    "validation_url": "https://uat-api.mychurch.co.ke/api/v1/callback",
    "confirmation_url": "https://uat-api.mychurch.co.ke/api/v1/confirm"
  }
}

If Safaricom refuses

Safaricom usually accepts production URL registration only once per shortcode. If your paybill was registered before (for example with an older system), ok is false with Safaricom's reason. Ask Safaricom (M-Pesa business support, or your account manager) to clear the existing URLs, then register again, or ask [email protected] to check: paybills already pointing at MyChurch need nothing.

Step 4: collection accounts

Create a collection account for each thing members give to (Tithe, Offering, Building Fund...) under Giving, Collection accounts, each with the account number members will type. Numbers are matched without regard to case, within the paybill. Avoid numbers that start with a reserved prefix (FR-, EV- and the others in Account numbers).

Step 5: a test payment

From any phone, pay KES 10 to the paybill with account number OFFERING (or one of yours).
Within a minute the payment appears in the collection ledger and the phone gets a receipt SMS (if the church has a sender ID).
If it shows in Incoming payments instead, the account number did not match: check the spelling of the collection account.
If nothing appears after a few minutes, check that the initiator is stored (Step 2) and that registration succeeded (Step 3).

Payment prompts (STK push)

With a passkey stored and allow_stk_push on, members can pay from the app and USSD without typing the paybill. Turn prompts off and on without touching the credentials:

POSThttps://uat-api.mychurch.co.ke/v1/paybills/{uuid}/stkchurch:paybills:manage

json

{ "allow_stk_push": false }