Introduction

Welcome to the Church Management System API v2. This RESTful API provides comprehensive access to church management features including member management, contributions, events, and new M-Pesa payment integration.

New in v2.0: M-Pesa payment integration, member transfer requests, enhanced contribution tracking with SMS receipts, and improved dashboard analytics.
API Features: RESTful design, JWT authentication, rate limiting, comprehensive error handling, and detailed documentation.

Base URL & Headers

All API requests should be made to the following base URL:

Base URL 
https://apidev.royexsolutions.co.ke/api/v1

Required Headers

All requests must include the following headers:

Header Value Required For
Content-Type application/json POST, PUT, PATCH requests
Accept application/json All requests
Authorization Bearer YOUR_AUTH_TOKEN Protected endpoints

Authentication

Most endpoints require JWT (JSON Web Token) authentication. Obtain your token by logging in through the authentication endpoints.

Getting an Authentication Token

First, register or login to get your authentication token:

POST /auth/register

Register a new user account

Request Body 
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "254712345678",
  "password": "password123",
  "password_confirmation": "password123",
  "church_id": 1
}
Response (201 Created) 
{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "254712345678",
      "church_id": 1
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  },
  "timestamp": "2026-02-10T12:34:56Z"
}
POST /auth/login

Authenticate user and receive JWT token

Request Body 
{
  "email": "john@example.com",
  "password": "password123"
}
Response (200 OK) 
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "254712345678",
      "church_id": 1
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  },
  "timestamp": "2026-02-10T12:34:56Z"
}
Security Note: Always use HTTPS. Store tokens securely and never expose them in client-side code. Tokens expire after 24 hours.

Public Endpoints

Endpoints accessible without authentication.

Church Information

GET /churches

Get list of active churches for registration

Response (200 OK) 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Nairobi Central SDA Church",
      "location": "Nairobi, Kenya",
      "phone": "254712345678",
      "email": "info@nairobi-sda.org",
      "status": "active"
    },
    {
      "id": 2,
      "name": "Mombasa Coastal SDA Church",
      "location": "Mombasa, Kenya",
      "phone": "254712345679",
      "email": "info@mombasa-sda.org",
      "status": "active"
    }
  ],
  "timestamp": "2026-02-10T12:34:56Z"
}

M-Pesa Callbacks (Safaricom)

POST /mpesa/validation

M-Pesa validation callback (called by Safaricom)

Request Body (from Safaricom) 
{
  "TransactionType": "Pay Bill",
  "TransID": "RI7046YUR7I",
  "TransTime": "20240115123456",
  "TransAmount": "100.00",
  "BusinessShortCode": "174379",
  "BillRefNumber": "TITHE001",
  "InvoiceNumber": "",
  "OrgAccountBalance": "",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "John"
}
Response (Expected by Safaricom) 
{
  "ResultCode": 0,
  "ResultDesc": "Accepted"
}
POST /mpesa/confirmation

M-Pesa confirmation callback (called by Safaricom)

Request Body (from Safaricom) 
{
  "TransactionType": "Pay Bill",
  "TransID": "RI7046YUR7I",
  "TransTime": "20240115123456",
  "TransAmount": "100.00",
  "BusinessShortCode": "174379",
  "BillRefNumber": "TITHE001",
  "InvoiceNumber": "",
  "OrgAccountBalance": "100000.00",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "John"
}

Authentication (Protected)

Endpoints that require authentication token in the Authorization header.

User Profile

GET /auth/profile

Get current authenticated user profile

PUT /auth/profile

Update user profile information

Request Body 
{
  "name": "John Updated",
  "email": "john.updated@example.com",
  "phone": "254712345679"
}
POST /auth/change-password

Change user password

Request Body 
{
  "current_password": "oldpassword",
  "password": "newpassword123",
  "password_confirmation": "newpassword123"
}
POST /auth/logout

Logout user (revoke token)

Dashboard

Dashboard-related endpoints for analytics and statistics.

GET /dashboard

Get main dashboard data

GET /dashboard/statistics

Get detailed dashboard statistics

Members Management

Manage church members with CRUD operations and statistics.

Member Operations

GET /members

Get paginated list of members

GET /members/statistics

Get members statistics

GET /members/1

Get details of a specific member

POST /members Admin Only

Create a new member (Admin permission required)

Request Body 
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "phone": "254712345680",
  "gender": "female",
  "date_of_birth": "1990-05-15",
  "marital_status": "single",
  "membership_status": "active"
}
PUT /members/1 Admin Only

Update member details (Admin permission required)

Request Body 
{
  "first_name": "Jane Updated",
  "last_name": "Smith",
  "email": "jane.updated@example.com",
  "membership_status": "active"
}
DELETE /members/1 Admin Only

Delete a member (Admin permission required)

Contributions (Legacy)

Legacy contribution endpoints for backward compatibility.

GET /contributions/my

Get current user's tithes and offerings (legacy endpoint)

GET /contributions/summary

Get summary of user's contributions (legacy endpoint)

POST /contributions/record

Record a contribution (tithe or offering) - legacy endpoint

Request Body 
{
  "type": "tithe",
  "amount": 1000.50,
  "date": "2026-02-10",
  "payment_method": "mpesa",
  "notes": "January tithe"
}

My Contributions (NEW - M-Pesa Integrated)

Enhanced contribution system with M-Pesa integration and SMS receipts.

Contribution Management

GET /my-contributions

Get user's contributions with M-Pesa integration

GET /my-contributions/summary

Get detailed contribution summary

POST /my-contributions

Create a new contribution with optional M-Pesa payment

Request Body 
{
  "type": "tithe",
  "amount": 1500.00,
  "payment_method": "mpesa",
  "phone_number": "254712345678",
  "offering_type_id": 1,
  "notes": "January tithe payment"
}
GET /my-contributions/1

Get details of a specific contribution

GET /my-contributions/1/verify-mpesa

Check M-Pesa payment status for a contribution

GET /my-contributions/1/receipt

Download contribution receipt PDF

POST /my-contributions/1/send-receipt-sms

Send contribution receipt via SMS

POST /my-contributions/mpesa/callback

M-Pesa STK Push callback endpoint (called by Safaricom)

Request Body (from Safaricom) 
{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_220120241246123456",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {
            "Name": "Amount",
            "Value": 100
          },
          {
            "Name": "MpesaReceiptNumber",
            "Value": "RI7046YUR7I"
          },
          {
            "Name": "Balance"
          },
          {
            "Name": "TransactionDate",
            "Value": 20240115123456
          },
          {
            "Name": "PhoneNumber",
            "Value": 254712345678
          }
        ]
      }
    }
  }
}

Member Transfers (NEW)

Manage member transfer requests between churches with approval workflow.

Member Transfer Requests

GET /member-transfers/my

Get member's own transfer requests

POST /member-transfers

Submit a member transfer request

Request Body 
{
  "reason": "Relocating to Nairobi",
  "destination_church_id": 2,
  "transfer_date": "2024-02-01",
  "notes": "Will be moving to Nairobi for work"
}
DELETE /member-transfers/1

Cancel a transfer request (only if pending)

Leadership Approval

GET /member-transfers Leadership

Get all transfer requests (Leadership permission required)

GET /member-transfers/pending Leadership

Get pending transfer requests (Leadership permission required)

GET /member-transfers/1

Get details of a specific transfer request

PATCH /member-transfers/1/approve Leadership

Approve a transfer request (Leadership permission required)

Request Body 
{
  "approval_notes": "Transfer approved by church board"
}
PATCH /member-transfers/1/reject Leadership

Reject a transfer request (Leadership permission required)

Request Body 
{
  "rejection_reason": "Transfer cannot be approved at this time"
}
PATCH /member-transfers/1/complete Admin Only

Mark transfer as completed (Admin permission required)

Request Body 
{
  "completion_notes": "Transfer completed successfully"
}
GET /member-transfers/statistics Admin Only

Get transfer statistics (Admin permission required)

Finance Management

Financial management endpoints for tithes, offerings, and reports.

Tithe Management

GET /finance/tithe Treasurer/Admin

Get all tithes (Treasurer/Admin permission required)

POST /finance/tithe Treasurer/Admin

Record a tithe (Treasurer/Admin permission required)

Request Body 
{
  "member_id": 1,
  "amount": 1500.75,
  "payment_date": "2026-02-10",
  "payment_method": "cash",
  "month": 1,
  "year": 2024
}
GET /finance/tithe/summary/1

Get giving summary for a specific member

Offering Management

GET /offerings

Get all offerings

POST /offerings

Create a new offering

Request Body 
{
  "member_id": 1,
  "offering_type_id": 1,
  "amount": 500.00,
  "offering_date": "2026-02-10",
  "payment_method": "cash",
  "notes": "Thanksgiving offering"
}
POST /offerings/mpesa

Initiate M-Pesa payment for offering

Request Body 
{
  "member_id": 1,
  "offering_type_id": 1,
  "amount": 500.00,
  "phone_number": "254712345678",
  "description": "Special offering"
}
GET /offerings/statistics

Get offering statistics

GET /offerings/1

Get details of a specific offering

GET /offerings/types Admin Only

Get all offering types (Admin permission required)

Reports & Receipts

GET /finance/reports Treasurer/Admin/Pastor

Get finance reports (Treasurer/Admin/Pastor permission required)

GET /finance/receipts/1 Treasurer/Admin/Pastor

Get receipt details (Treasurer/Admin/Pastor permission required)

Events

Manage church events and registrations.

GET /events

Get all events

GET /events/my-events

Get events registered by current user

GET /events/1

Get details of a specific event

POST /events/1/register

Register for an event

DELETE /events/1/register

Cancel event registration

POST /events Admin/Pastor

Create a new event (Admin/Pastor permission required)

Request Body 
{
  "title": "Youth Conference",
  "description": "Annual youth conference",
  "start_date": "2024-02-15",
  "end_date": "2024-02-17",
  "venue": "Church Hall",
  "event_type": "conference"
}
PUT /events/1 Admin/Pastor

Update an event (Admin/Pastor permission required)

Request Body 
{
  "title": "Youth Conference Updated",
  "description": "Updated annual youth conference",
  "venue": "Main Sanctuary"
}
DELETE /events/1 Admin/Pastor

Delete an event (Admin/Pastor permission required)

Announcements

Manage church announcements.

GET /announcements

Get all announcements

GET /announcements/1

Get details of a specific announcement

Notifications

Manage user notifications.

GET /notifications

Get user notifications

POST /notifications/1/read

Mark a notification as read

POST /notifications/read-all

Mark all notifications as read

Church Services

Manage church services and attendance.

GET /services

Get church services

POST /services

Record a church service

Request Body 
{
  "service_type": "divine_service",
  "service_date": "2024-01-14",
  "start_time": "10:00",
  "end_time": "12:30",
  "preacher_name": "Pastor John",
  "sermon_title": "The Power of Faith",
  "attendance_count": 150,
  "offering_amount": 12500.50
}

Families

Manage church families and their members.

GET /families

Get all families

POST /families

Create a new family

Request Body 
{
  "family_name": "Smith Family",
  "head_of_family_id": 1,
  "address": "123 Main St, Nairobi",
  "phone": "254712345678"
}
GET /families/1

Get details of a specific family

M-Pesa Payments

Process payments through Safaricom M-Pesa with STK Push.

POST /mpesa/stkpush

Initiate M-Pesa payment

Request Body 
{
  "phone_number": "254712345678",
  "amount": 500,
  "account_reference": "TITHE-001",
  "description": "January Tithe"
}
GET /mpesa/transactions

Get M-Pesa transaction history

Settings

System settings and configuration endpoints.

GET /settings/church-info

Get church information

GET /settings/app-config

Get application configuration

Response Format

All API responses follow a consistent JSON format:

Success Response 
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data varies by endpoint
  },
  "timestamp": "2026-02-10T12:34:56Z"
}

Pagination

List endpoints return paginated responses:

Paginated Response 
{
  "success": true,
  "data": [
    // Array of items
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 20,
    "to": 20,
    "total": 95
  },
  "links": {
    "first": "https://apidev.royexsolutions.co.ke/api/v1/members?page=1",
    "last": "https://apidev.royexsolutions.co.ke/api/v1/members?page=5",
    "prev": null,
    "next": "https://apidev.royexsolutions.co.ke/api/v1/members?page=2"
  },
  "timestamp": "2026-02-10T12:34:56Z"
}

Rate Limits

API requests are limited to 1000 requests per hour per authenticated user. Rate limit information is included in response headers:

Rate Limit Headers 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Rate Limit Exceeded: When you exceed the rate limit, you'll receive a 429 status code with a Retry-After header indicating when you can retry.

Error Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required or invalid token
403 Forbidden Insufficient permissions
404 Not Found Resource not found
422 Unprocessable Entity Validation error
429 Too Many Requests Rate limit exceeded (1000 requests/hour)
500 Internal Server Error Server error
Error Response Example 
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  },
  "timestamp": "2026-02-10T12:34:56Z"
}

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your church management system.

Coming Soon: Webhook functionality is currently under development and will be available in the next release.