API

Payouts API

Schedule creditor, salary and refund payments out of your Netcash account, follow their status, and cancel them.

On this page

Overview
The payout object
Statuses
Schedule a payout
List payouts
Get a payout
Cancel a payout
Webhook events
Errors

Overview#

Payouts are payments out of your Netcash account to a bank account: supplier and creditor payments, salaries, and refunds to customers. They need a Netcash Creditor & Salary Payments gateway (the netcash_creditor module) under Settings → Gateways; salaries also need its Salary payments service key. No plan feature is required beyond API access. Payouts are in ZAR.

Payout endpoints
Endpoint	Purpose
`POST /api/v1/payouts`	Schedule a payout
`GET /api/v1/payouts`	List, filter by status, kind or customer
`GET /api/v1/payouts/{id}`	Get one payout
`POST /api/v1/payouts/{id}/cancel`	Cancel before it is submitted

Wherever a path takes {id}, you can also use the payout reference. To refund a credit note by payout, use POST /api/v1/credit-notes/{id}/refund with method: "payout" instead, so the credit balance is updated.

The payout object#

The same object is returned by every payout endpoint and sent as data in payout.* webhooks.

Payout

{
  "object": "payout",
  "id": "cmg3p4q5r0003pay0001abcd",
  "reference": "PAY-000031",
  "kind": "creditor",
  "status": "scheduled",
  "beneficiaryName": "Acme Supplies",
  "beneficiaryEmail": "[email protected]",
  "bankName": "FNB",
  "accountLast4": "4821",
  "amount": 12500,
  "currency": "ZAR",
  "description": "Invoice AS-2291",
  "statementRef": "CentraPoint AS-2291",
  "actionDate": "2026-10-01T00:00:00.000Z",
  "submittedAt": null,
  "paidAt": null,
  "failureReason": null,
  "customer": null,
  "creditNote": null,
  "createdAt": "2026-09-27T10:00:00.000Z",
  "updatedAt": "2026-09-27T10:00:00.000Z"
}

Payout fields
Field	Type	Description
`object`required	string	Always `payout`.
`id`required	string	CentraPoint payout ID.
`reference`required	string	Your account reference for the payment in the Netcash batch.
`kind`required	string	`creditor`, `salary` or `refund`.
`status`required	string	See Statuses.
`beneficiaryName, beneficiaryEmail`required	string / string \| null	Who is paid.
`bankName, accountLast4`required	string \| null	The only bank details returned.
`amount, currency`required	number, string	Always `ZAR`.
`description`required	string \| null	Your internal description.
`statementRef`required	string \| null	What the beneficiary sees on their statement (max 20 chars).
`actionDate`required	string	The payment date (UTC midnight of that calendar day).
`submittedAt, paidAt`required	string \| null	When it went to Netcash, and when it was marked paid.
`failureReason`required	string \| null	Why it failed (when `failed`).
`customer`required	object \| null	`{ id, externalReference, email }` when linked to a customer.
`creditNote`required	object \| null	`{ id, number }` when it pays back a credit note.
`createdAt, updatedAt`required	string

Statuses#

Payout statuses
status	Meaning
`scheduled`	Waiting for its action date. Can be cancelled.
`submitted`	Sent to Netcash in a batch (by default one day before the action date, per the gateway's setting).
`paid`	Netcash loaded the batch and the action date has passed.
`failed`	Rejected by Netcash or the upload failed; see `failureReason`. A credit note's reserved amount is released.
`cancelled`	Cancelled before submission.

Schedule a payout#

POST/api/v1/payouts

Schedule payout fields
Field	Type	Description
`kind`required	string	`creditor`, `salary` or `refund`.
`beneficiaryName`required	string	1–50 chars.
`bank`required	object	`accountHolder`, `accountNumber`, `branchCode`, `accountType` (`current`, `savings` or `transmission`), optional `bankName`. Invalid details return `400`.
`amount`required	number	Greater than 0, up to 5 000 000.
`actionDate`required	string (YYYY-MM-DD)	Payment date; today or later (South African time).
`providerId`optional	string	Your Netcash Creditor & Salary Payments gateway. Default: the first enabled one (the default gateway first); 400 if none.
`beneficiaryEmail`optional	string	Optional.
`description`optional	string	Up to 1000 chars.
`statementRef`optional	string	Up to 20 chars; default the beneficiary name.
`customerId / customerExternalReference`optional	string	Optionally link the payout to one of your customers (at most one of the two; unknown returns `400`).

curl -X POST "https://app.centrapoint.co.za/api/v1/payouts" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: d2f4a6c8-7e9b-4c1d-b3f5-8a0c2e4b6d17" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "creditor",
    "beneficiaryName": "Acme Supplies",
    "beneficiaryEmail": "[email protected]",
    "bank": {
      "accountHolder": "Acme Supplies (Pty) Ltd",
      "accountNumber": "62000004821",
      "branchCode": "250655",
      "accountType": "current",
      "bankName": "FNB"
    },
    "amount": 12500,
    "actionDate": "2026-10-01",
    "description": "Invoice AS-2291",
    "statementRef": "CentraPoint AS-2291"
  }'

Returns 201 with the payout object and emits payout.scheduled.

List payouts#

GET/api/v1/payouts

List query parameters
Field	Type	Description
`status`optional	string	`scheduled`, `submitted`, `paid`, `failed` or `cancelled`.
`kind`optional	string	`creditor`, `salary` or `refund`.
`customerId`optional	string	Only payouts linked to this customer.
`limit, startingAfter`optional		Keyset pagination: the response is `{ data, hasMore, nextCursor }`, newest first.

curl -X GET "https://app.centrapoint.co.za/api/v1/payouts?status=scheduled&kind=salary" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a payout#

GET/api/v1/payouts/{id}

curl -X GET "https://app.centrapoint.co.za/api/v1/payouts/cmg3p4q5r0003pay0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Cancel a payout#

POST/api/v1/payouts/{id}/cancel

Cancels a scheduled payout. No body is needed. Once submitted to Netcash it can't be cancelled here (400). If the payout pays back a credit note, its amount returns to the credit note's balance. Returns the updated payout and emits payout.cancelled.

curl -X POST "https://app.centrapoint.co.za/api/v1/payouts/cmg3p4q5r0003pay0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: e5a7c9b1-8f0d-4e2a-b4c6-9d1f3a5c7e80"

Webhook events#

payout.scheduled, payout.submitted, payout.paid, payout.failed and payout.cancelled are sent to your webhook endpoints with the payout object as data, including payouts scheduled from the dashboard or for credit notes.

Errors#

Payout errors
Status	error	When
400	`invalid_request`	Validation failed; invalid bank details; no enabled payout gateway or unknown providerId; gateway disabled; salary without a salary service key; action date in the past; customer not found; unknown status/kind filter; cancelling a payout that is no longer scheduled.
403	`plan_restricted / account_restricted`	Plan lacks the API, or the account is read-only (writes).
404	`not_found`	No payout with this ID or reference in your organisation.
409	`idempotency_conflict`	Idempotency-Key reused with a different body.
401 / 429 / 500	`unauthorized` / `rate_limited` / `internal_error`	See Errors