Giving, paybills and pledges

The api never credits a payment from a callback alone: each M-Pesa payment is verified with Safaricom first, and anything it cannot place waits on the incoming payments list. Payment verification explains why, and How giving works walks the whole flow. Read routes on this page also accept head_office:churches:view and system:churches:view with an X-Church header, except the paybill and bank routes.

Collection accounts

A collection account is what a member types as the M-Pesa account number: TITHE, BUILDING, OFFERING. Each sits on one paybill or one bank account, and its number is unique on that channel. Numbers may not start with a reserved prefix (FR- OP- MP- CLS- CAR- EV- EVS- MERCH- CH- QR-); see Account numbers.

# 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/collection-accounts \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Building Fund",
    "account": "BUILDING",
    "paybill_uuid": "3c9a7b21-0000-4000-8000-00000000b001",
    "goal": 2500000,
    "send_alert": true,
    "message": "Dear [fname], we have received KES [amount] for [account_name]. God bless you."
  }'

The collection ledger

Every credited collection, whatever the channel. Lists are read for a date window (from, to; default the current month).

# 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/collection-transactions \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_uuid": "8e4d2f10-0000-4000-8000-00000000a201",
    "amount": 1500,
    "payment_mode": "cash",
    "member_uuid": "0b6f4c1e-1111-4a2b-9c3d-000000000001",
    "reference": "ENV-0412",
    "transaction_time": "2026-11-01"
  }'

Incoming payments

Payments that reached a paybill or bank account but could not be credited on their own: an account number no collection account matches, a failed verification, a Safaricom outage. Nothing is dropped. Assigning a payment hands it back to the payments worker, which credits it (verifying it first if Safaricom has not confirmed it yet); the api never credits on its own.

Staff may read the review list with system:churches:view; head office users cannot.

Pledges

Fundraisers

A fundraiser has its own FR- account number, a target and dates, and takes pledges of its own.

Contribution programs

Paybills and tills

A church's own M-Pesa paybill or till, with its Daraja credentials. Secrets are encrypted at rest and never returned: a paybill shows has_pass_key, has_consumer_secret and a consumer_key_hint instead. Leave a secret blank on update to keep the stored one. Step by step: Paybill and till setup.

# 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/3c9a7b21-0000-4000-8000-00000000b001/register-c2b" \
  -H "Authorization: Bearer $MYCHURCH_TOKEN"

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

Bank accounts and KCB

Bank accounts that receive giving (Equity, KCB, Co-operative Bank, NCBA), with the bank's integration credentials where the bank issues them. Bitwise staff can manage these for a church with system:integrations:manage. See Bank integrations.

Reconciliation uploads

Upload an M-Pesa organisation portal statement or a bank export. The imports worker matches each credit line by receipt and amount with the ledger and reports rows_matched and rows_unmatched. It credits nothing: a payment missing from the ledger reaches the incoming payments list through the normal verified path.