Recurring payments let you charge customers at regular intervals. Useful for subscriptions, rent collection, loan repayments, and any scenario where you need to collect money on a schedule.
How it works
Create a recurring payment
Define the amount, interval, payment method, and customer phone number.
Simiz processes automatically
On each scheduled date, Simiz initiates a payment via the configured payment method.
Get notified via webhooks
Receive recurring.executed, recurring.failed, or recurring.paused events after each execution.
API reference
Base path: /api/v1/projects/{projectId}/recurring
Create a recurring payment
POST /api/v1/projects/{projectId}/recurring
{
"customerId": "cus_abc123",
"amount": 5000,
"currency": "XAF",
"interval": "MONTHLY",
"intervalCount": 1,
"paymentMethod": "ORANGE_MONEY",
"payerPhone": "237690000000",
"startDate": "2026-04-01T00:00:00Z",
"maxCycles": 12,
"description": "Monthly subscription",
"metadata": { "planId": "premium" }
}
Required fields
| Field | Type | Description |
|---|
amount | number | Amount per cycle (minimum 100 XAF) |
interval | enum | DAILY, WEEKLY, MONTHLY, or YEARLY |
paymentMethod | enum | Payment method (e.g. ORANGE_MONEY, MTN_MOMO) |
payerPhone | string | Payer’s phone number (e.g. 237690000000) |
startDate | string | ISO 8601 start date |
Optional fields
| Field | Type | Description |
|---|
customerId | UUID | Link to a customer profile |
currency | string | Currency code (default: XAF) |
intervalCount | number | Intervals between payments (1-12, default: 1) |
endDate | string | ISO 8601 end date |
maxCycles | number | Maximum number of payment cycles |
description | string | Description |
metadata | object | Additional key-value metadata |
Available endpoints
| Method | Endpoint | Description |
|---|
POST | / | Create a recurring payment |
GET | / | List all recurring payments (with filters) |
GET | /stats | Get recurring payment statistics |
GET | /{id} | Get a single recurring payment |
PUT | /{id} | Update a recurring payment |
POST | /{id}/pause | Pause a recurring payment |
POST | /{id}/resume | Resume a paused payment |
POST | /{id}/cancel | Cancel a recurring payment |
GET | /{id}/executions | Get execution history |
Statuses
| Status | Description |
|---|
ACTIVE | Currently executing on schedule |
PAUSED | Temporarily paused (can be resumed) |
CANCELLED | Permanently stopped |
COMPLETED | All scheduled cycles finished |
Webhook events
| Event | Trigger |
|---|
recurring.created | A recurring payment is created |
recurring.executed | A scheduled payment executed successfully |
recurring.failed | A scheduled payment failed |
recurring.paused | A recurring payment was paused (manually or after failures) |
recurring.cancelled | A recurring payment was cancelled |
When a recurring payment reaches the failureCount threshold, it is automatically paused and a recurring.paused event is emitted.
