Mandates
Update Subscription
Freeze or unfreeze a mandate, or update the instalment amount for future collections
Freeze or unfreeze a mandate, and/or update the instalment amount for all future collections.
Endpoint
POST /api/mandates/{mandate_id}/subscription
Authentication: Required (API Key)
Description
Use this endpoint to pause collections on a mandate by freezing it, to resume collections by unfreezing it, or to change the amount collected on future instalments. At least one of pause_collection or amount must be provided.
Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
mandate_id | integer | Yes | The NjiaPay internal mandate ID |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pause_collection | boolean | No | true to freeze the mandate (stops all future collections), false to unfreeze. Omit to leave unchanged. |
amount | integer | No | New instalment amount in minor units applied to all future collections. Omit to leave unchanged. |
At least one of
pause_collection or amount must be set in the request body.Example Requests
curl -X POST "https://api.njiapay.com/api/mandates/42/subscription" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pause_collection": true}'
curl -X POST "https://api.njiapay.com/api/mandates/42/subscription" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 1200}'
// Freeze mandate
const response = await fetch(
"https://api.njiapay.com/api/mandates/42/subscription",
{
method: "POST",
headers: {
Authorization: `Bearer ${YOUR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ pause_collection: true }),
},
);
const result = await response.json();
console.log("Frozen:", result.frozen);
import requests
# Freeze mandate
response = requests.post(
"https://api.njiapay.com/api/mandates/42/subscription",
headers={
"Authorization": f"Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
},
json={"pause_collection": True},
)
result = response.json()
print("Frozen:", result["frozen"])
Response
Success (200 OK)
{
"frozen": true,
"instalment_amount": null
}
| Field | Type | Description |
|---|---|---|
frozen | boolean | null | true = mandate frozen; false = mandate unfrozen; null = freeze state unchanged. When frozen, no instalments are collected. |
instalment_amount | number | null | Updated instalment amount in minor units. May differ from instalment_amount on the mandate object as it reflects the provider's confirmed value. null if not changed. |
Error Responses
403 Forbidden
{
"detail": "Mandate does not belong to this merchant"
}
404 Not Found
{
"detail": "No active mandate found for this reference_id"
}
422 Validation Error
{
"detail": "Either pause_collection or amount must be set"
}
Causes:
- Neither
pause_collectionnoramountwas provided in the request body
502 Bad Gateway
{
"detail": "Mandate subscription update failed at payment provider"
}
Causes:
- The payment provider returned an error or is unreachable