Mandates
Get Mandate
Retrieve the current state of a mandate from the payment provider
Retrieve the live state of a mandate, fetched directly from the payment provider.
Endpoint
GET /api/mandates/{mandate_id}
Authentication: Required (API Key)
Description
Returns the current details of a mandate, including its status, collection amounts, and schedule. The data is proxied directly from the DebiCheck provider, so it always reflects the latest state.
Mandates are created as part of a payment intent flow. See Create Payment Intent for how to set up the future_payments object that triggers mandate signing.
Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
mandate_id | integer | Yes | The NjiaPay internal mandate ID |
The mandate_id will be provided to you via webhook.
Example Request
curl -X GET "https://api.njiapay.com/api/mandates/42" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch("https://api.njiapay.com/api/mandates/42", {
headers: { Authorization: `Bearer ${YOUR_API_KEY}` },
});
const mandate = await response.json();
console.log("Status:", mandate.status);
import requests
response = requests.get(
"https://api.njiapay.com/api/mandates/42",
headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
)
mandate = response.json()
print("Status:", mandate["status"])
Response
Success (200 OK)
{
"contract_number": "MANDATE-12345",
"instalment_amount": 1000,
"maximum_amount": 1500,
"collection_day": 1,
"first_initiation_date": "2025-06-01T00:00:00Z",
"instalment_start_date": "2025-06-01T00:00:00Z",
"number_of_instalments": 11,
"registered_mandate": true,
"frozen": false,
"status": "active"
}
| Field | Type | Description |
|---|---|---|
contract_number | string | Unique contract identifier at the provider |
instalment_amount | integer | Scheduled collection amount per instalment in minor units |
maximum_amount | integer | Maximum amount that can be collected per instalment in minor units |
collection_day | integer | Day of the configured frequency on which collections occur |
first_initiation_date | string | null | Datetime of the first instalment initiation, if available |
instalment_start_date | string | Datetime from which instalments begin |
number_of_instalments | integer | null | Total number of instalments to collect. null for indefinite (subscription-based) |
registered_mandate | boolean | null | Whether the mandate is registered at the bank register |
frozen | boolean | If true, no collections are made against this mandate |
status | string | Current mandate status — see Mandate statuses |
Mandate statuses
| Status | Description |
|---|---|
initiated | Mandate created; customer not yet redirected to sign |
pending | Signing in progress at the provider |
authorized | Successfully signed by the customer |
active | Approved by the bank and ready for collections |
canceled | Cancelled by the customer or the merchant |
failed | Signing or authorisation failed |
suspended | Suspended at the bank register; can be reactivated by the bank |
Error Responses
403 Forbidden
{
"detail": "Mandate does not belong to this merchant"
}
404 Not Found
{
"detail": "No mandate found for this ID"
}
502 Bad Gateway
{
"detail": "Mandate retrieval failed at payment provider"
}
Causes:
- The payment provider returned an error or is unreachable