Build Financial Applications on ChamaPay Infrastructure

Authentication Method

All API requests require authentication using a Bearer token. Include your API key in the Authorization header.

Header Format

Authorization: Bearer cpk_live_your_api_key:your_api_secret
Content-Type: application/json

Prevent Duplicate Operations

To safely retry requests without duplication, include an Idempotency-Key header with a unique value for each new request.

Header Format

Idempotency-Key: unique-request-id-abc123
Authorization: Bearer cpk_live_xxxxxxxxxxxxx
Content-Type: application/json

Example Request with Idempotency Key

curl -X POST https://api.chamapay.co.ke/v1/contributions \
  -H "Authorization: Bearer cpk_live_xxxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"member_id": "MFT001", "amount": 5000}'

Retrieve a paginated list of all members in your chama. Supports filtering by status and search queries.

Query Parameters

Response Schema

Example Request

curl -X GET "https://api.chamapay.co.ke/v1/members?status=Active&page=1&limit=20" \
  -H "Authorization: Bearer cpk_live_xxxxx"

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 123,
      "member_id": "MFT001",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+254712345678",
      "status": "Active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "pages": 8
  }
}

Create a new member in your chama. Requires write permission.

Request Body

Example Request

curl -X POST https://api.chamapay.co.ke/v1/members \
  -H "Authorization: Bearer cpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "phone": "+254798765432",
    "id_number": "12345678"
  }'

Possible Errors

Retrieve member contributions with advanced filtering by date range, member, and contribution type.

Query Parameters

Configure your webhook URLs in the ChamaPay Admin Dashboard to receive POST requests for specific system events.

Supported Events

• contribution.created — Fired instantly when a new payment is recorded.
• loan.approved — Fired when a pending loan application is approved by the committee.
• member.registered — Fired when a new member joins the group.
• fine.issued — Fired when a penalty is applied to a member.

Webhook Payload Example

{
  "event": "contribution.created",
  "data": {
    "member_id": "MFT001",
    "amount": 5000,
    "date": "2026-04-30"
  }
}

Security: Signature Verification

Every webhook request includes an X-ChamaPay-Signature header. You MUST verify this using your Webhook Secret to prevent spoofing.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto.createHmac('sha256', secret)
                     .update(JSON.stringify(payload))
                     .digest('hex');
  return hash === signature;
}

Complete V1 API Reference

ChamaPay offers a comprehensive suite of endpoints to manage every aspect of your organization. All endpoints follow the same standard RESTful conventions and authentication patterns.

Error Response Format & Specific Error Codes

Unlike generic APIs, ChamaPay returns extremely precise error.code values so your application can programmatically handle exact failure scenarios (e.g., prompting a user if an email is taken vs if their phone is invalid).

{
  "success": false,
  "error": {
    "code": "MEMBER_EXISTS_EMAIL",
    "message": "The email address john@example.com is already registered to another member.",
    "details": "Please provide a unique email or contact support for account recovery."
  }
}