A mandate is a customer's authority to debit their bank account through your Netcash debit order account. Read the Debit orders guide for how mandates are authorised, approved, batched and collected. Batches, batch approval, unpaids and debit order settings stay in the dashboard.
Mandate endpoints
Endpoint
Purpose
POST /api/v1/mandates
Create a mandate
GET /api/v1/mandates
List mandates
GET /api/v1/mandates/{id}
Get a mandate
PATCH /api/v1/mandates/{id}
Change amount or debit day; pause, resume or cancel
Exactly one: the ID, or { "id" } / { "externalReference" }.
bank.branchCoderequired
string
6 digits.
bank.accountNumberrequired
string
Digits (spaces and dashes are removed); validated for live Netcash accounts.
bank.accountHolderrequired
string
2–30 characters.
bank.accountTypeoptional
string
current (default), savings or transmission.
bank.nameoptional
string
Bank name, up to 60 characters.
amountrequired
number
Greater than 0, up to 1 000 000 (ZAR).
frequencyoptional
string
Default monthly.
debitDayoptional
integer
1–31; default from your debit order settings.
startDate, endDateoptional
string (date)
YYYY-MM-DD. Start today or later (default today); end after start.
providerIdoptional
string
Netcash provider; default your first enabled one.
productId, subscriptionIdoptional
string
Link a product, or the customer subscription to collect. Not a subscription your platform bills (collectionMethod: external): 409 external_subscription.
descriptionoptional
string
Up to 500 characters; defaults to the product name.
idNumberoptional
string
Account holder's ID number (up to 20 characters).
notesoptional
string
Internal notes, up to 2000 characters.
authorityoptional
string
agreement (default), emandate or offline. See below.
Returns 201 with the mandate plus warnings (non-blocking bank validation messages) and, for agreement authority, agreementSent: { id, emailed, expiresAt }. Supports the Idempotency-Key header.
CentraPoint emails the customer your debit order agreement (Debit orders → Settings) to sign online. The signing URL is not in the create response; issue one with the agreement endpoint if you want to show it yourself.
emandate
Netcash creates an electronic mandate for the customer to sign; its link is returned as eMandateUrl. Netcash reports the signature back to CentraPoint.
offline
You already hold a signed mandate. It is marked authorised and becomes active at once, unless your settings require mandate approval.
Send at least one field. A pending mandate can't be set active (409): it activates once authorised and approved. The Idempotency-Key header is not used.
Renders your agreement template for this mandate and withdraws any agreement still open. The signUrl works for 14 days; treat it as a secret. This endpoint is never replayed from an Idempotency-Key, so each call issues a new link.
Validation failed: bank details, start date in the past, unknown customer/product/subscription, no Netcash provider, Netcash rejected the e-mandate, offline without confirmOfflineMandate.
403
plan_restricted
No REST API or Debit orders in your plan.
403
plan_limit / account_restricted
Mandate limit reached, or the account is read-only.
404
not_found
No mandate with this ID in your organisation.
409
invalid_request
PATCH status: "active" on a mandate that isn't paused.
409
idempotency_conflict
Idempotency-Key reused with a different body (create).
409
external_subscription
Create with the subscriptionId of a subscription your platform bills (collectionMethod: external).