CRDB Direct Debit API - ClickPesa Documentation

The CRDB Direct Debit API lets you request mandate approvals for recurring collections from customers’ CRDB bank accounts, receive mandate status callbacks, and get payment events through webhooks.

Prerequisites

Activate CRDB Direct Debit for your merchant account in the Merchant Dashboard.
API keys — Create an Application with the Collection API feature enabled.
Authorization token — Use your API keys to Generate an Authorization Token.

How It Works

Step 1 – Request Mandate Approval

Request Mandate Approval

Request mandate approval and create the linked payment schedule. Provide customer details, CRDB debit account, SimBanking phone number, dates, frequency, installment amount, and a mandate callback URL.

The response includes mandateRequestId, initial mandateStatus (REQUESTED), total amount, and number of installments.

Step 2 – Receive Mandate Status Callbacks

ClickPesa sends an HTTP POST to your mandateCallbackUrl when the mandate status changes to ACTIVE, REJECTED, or CANCELLED. Use mandateReference from the ACTIVE / REJECTED callback to correlate later installment payments (orderReference on payment webhooks matches this reference). See Mandate status callbacks below and the Request Mandate Approval reference.

Step 3 – Query Mandate Details (optional)

Get Mandate

Retrieve mandate status, CRDB account details, and payment plan summary using mandateRequestId.

Step 4 – Receive Payment Events

Configure Application webhooks (or merchant webhooks) for:

PAYMENT RECEIVED — installment collected successfully
PAYMENT FAILED — installment failed (for example insufficient funds, or mandate issues)

Payment payloads use "channel": "CRDB DIRECT DEBIT MANDATE". The orderReference field is the mandate reference from CRDB.

Step 5 – Cancel Mandate (optional)

Cancel Mandate

Cancel an ACTIVE mandate. The linked payment plan and unpaid cycles are cancelled when the plan is still active.

Mandate Status Callbacks

Callbacks are sent to the mandateCallbackUrl you provided when requesting mandate approval. ACTIVE

{
  "mandateRequestId": "69383ce4f8b5a8e2077df9c7",
  "mandateReference": "9009099",
  "mandateStatus": "ACTIVE",
  "mandateConfirmedAt": "2025-12-09T15:16:09.557Z"
}

REJECTED

{
  "mandateRequestId": "69382ac2358bdec745001d88",
  "mandateReference": "7767768907",
  "mandateStatus": "REJECTED",
  "mandateConfirmedAt": "2025-12-09T13:58:47.229Z"
}

CANCELLED

{
  "mandateRequestId": "693072b84e85ba41d1de3580",
  "mandateStatus": "CANCELLED",
  "mandateReference": "10540",
  "mandateCancelledAt": "2025-12-03T17:26:54.264Z"
}

Important Rules

One active mandate per CRDB debit account at a time
phoneNumber must be a SimBanking-registered number for the debit account (12 digits, country code, no +)
Dates: DD-MM-YYYY or YYYY-MM-DD
Frequency types: DAILY, WEEKLY, MONTHLY, YEARLY (optional frequency multiplier, default 1)
Cancel is only allowed when mandate status is ACTIVE

API Reference

Endpoint	Description
Request Mandate Approval	Request mandate approval and create the payment schedule
Get Mandate	Retrieve mandate status and plan summary
Cancel Mandate	Cancel an active mandate

​Prerequisites

​How It Works

​Step 1 – Request Mandate Approval

Request Mandate Approval

​Step 2 – Receive Mandate Status Callbacks

​Step 3 – Query Mandate Details (optional)

Get Mandate

​Step 4 – Receive Payment Events

​Step 5 – Cancel Mandate (optional)

Cancel Mandate

​Mandate Status Callbacks

​Important Rules

​API Reference

​Also See