Mandates

Amend Mandate

Request a change to the maximum collection amount on an active mandate

This endpoint allows you to change the maximum collection amount on an active mandate.

Submits an amendment request to the bank to update the maximum amount that can be collected per instalment. The amendment is not applied immediately, it takes effect once the purchaser and the issuing bank approve it, which is indicated by mandate_action_date in the response and may take several business days.

For registered mandates (identified through the registered_mandate field on the GET) amending the maximum amount is not possible. Instead a new mandate should be created with a higher maximum amount and once the new mandate is approved the old mandate should be canceled to prevent double charges.

maximum_amount sets the ceiling for what can be collected per instalment. To actually change the instalment amount for the upcoming instalments, use the Update Subscription endpoint.

Important Restrictions

Only mandates with status active can be amended
Only mandates without unresolved amendments can be amended.

Parameters

Path Parameters

Parameter	Type	Required	Description
`mandate_id`	integer	Yes	The NjiaPay internal mandate ID

Body Parameters

Parameter	Type	Required	Description
`max_amount`	integer	Yes	New maximum collection amount in minor units (cents). E.g., `1500` = R15.00

Example Request

curl -X POST "https://api.njiapay.com/api/mandates/42/amend" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_amount": 1500}'

const response = await fetch(
  "https://api.njiapay.com/api/mandates/42/amend",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${YOUR_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ max_amount: 1500 }),
  },
);

const result = await response.json();
console.log("Action date:", result.mandate_action_date);

import requests

response = requests.post(
    "https://api.njiapay.com/api/mandates/42/amend",
    headers={
        "Authorization": f"Bearer {YOUR_API_KEY}",
        "Content-Type": "application/json",
    },
    json={"max_amount": 1500},
)

result = response.json()
print("Action date:", result["mandate_action_date"])

Response

Success (200 OK)

{
  "contract_number": "MANDATE-12345",
  "transaction_type": "TT2",
  "mandate_action_date": "2025-07-01",
  "maximum_amount": 1500,
  "instalment_amount": null
}

Field	Type	Description
`contract_number`	string \| null	Contract number at the provider
`transaction_type`	string \| null	Transaction type used for the amendment
`mandate_action_date`	string \| null	Date when the amendment becomes active at the bank
`maximum_amount`	integer \| null	New maximum amount once the amendment is accepted by the bank
`instalment_amount`	integer \| null	New instalment amount once the amendment is accepted by the bank

Error Responses

403 Forbidden

{
  "detail": "Mandate does not belong to this merchant"
}

404 Not Found

{
  "detail": "No active mandate found for this reference_id"
}

409 Conflict

{
  "detail": "Mandate not active. Only active mandates can be amended"
}

502 Bad Gateway

{
  "detail": "Mandate amending failed at payment provider"
}

Causes:

The payment provider returned an error or is unreachable

Cancel Mandate

Cancel an active mandate, stopping all future collections

Update Subscription

Freeze or unfreeze a mandate, or update the instalment amount for future collections