CentraPoint

API

API reference

Endpoint reference generated from the CentraPoint OpenAPI 3.1 specification, with code samples.

On this page

CentraPoint API v1.23.0 · OpenAPI 3.1.0 · Base URL https://app.centrapoint.co.za

The CentraPoint REST API lets your systems manage customers, products, invoices, quotes and credit notes, schedule Netcash payouts, create hosted payment links, checkout sessions, coupons, EFT orders, subscription packages, plans and customer subscriptions, create and manage debit order mandates, manage customers' saved cards (and charge them from your own billing system) and read their account standing, list payments, receipts and refunds (with PDFs), check your organisation's entitlements and read reconciliation results. Every API key may make 120 requests per minute; responses report usage in X-RateLimit-* headers. All requests are authenticated with a tenant-scoped API key sent as a Bearer token. API access requires a plan that includes the REST API (Growth or higher).

Outbound webhooks that CentraPoint sends to your endpoints are described in the webhooks section. Gateway notification URLs (/api/webhooks/{type}) are called by payment gateways, not by API clients, and are therefore not part of this specification.

Download the machine-readable specification: openapi.json. Import it into Insomnia or a code generator.

Download Postman collection Every endpoint below, ready to send. See Use the Postman collection to set it up.

GETList payment links/api/v1/payment-linksPOSTCreate a payment link/api/v1/payment-linksGETGet a payment link/api/v1/payment-links/{id}GETList checkout sessions/api/v1/checkout-sessionsPOSTCreate a checkout session/api/v1/checkout-sessionsGETGet a checkout session/api/v1/checkout-sessions/{id}GETList coupons/api/v1/couponsPOSTCreate a coupon/api/v1/couponsPOSTValidate a coupon/api/v1/coupons/validateGETGet a coupon/api/v1/coupons/{id}PATCHUpdate a coupon/api/v1/coupons/{id}GETList customers/api/v1/customersPOSTCreate or upsert a customer/api/v1/customersGETLook up a customer/api/v1/customers/lookupGETGet a customer/api/v1/customers/{id}PATCHUpdate a customer/api/v1/customers/{id}POSTSend a customer portal link, or create a sign-in link/api/v1/customers/{id}/portal-linkGETGet a customer's account standing/api/v1/customers/{id}/standingGETList a customer's saved cards/api/v1/customers/{id}/cardsPOSTStart the hosted add-card page/api/v1/customers/{id}/cards/setupGETGet an add-card session/api/v1/customers/{id}/cards/setup/{sessionId}GETGet a saved card/api/v1/customers/{id}/cards/{cardId}DELETERemove a saved card/api/v1/customers/{id}/cards/{cardId}POSTMake a saved card the default/api/v1/customers/{id}/cards/{cardId}/defaultPOSTCharge a saved card/api/v1/customers/{id}/cards/{cardId}/chargesGETList invoices/api/v1/invoicesPOSTCreate an invoice/api/v1/invoicesGETGet an invoice/api/v1/invoices/{id}POSTSend an invoice/api/v1/invoices/{id}/sendPOSTIssue an invoice without emailing/api/v1/invoices/{id}/issuePOSTCancel an invoice/api/v1/invoices/{id}/cancelPOSTRecord an offline payment or allocate an existing payment/api/v1/invoices/{id}/paymentsGETDownload an invoice PDF/api/v1/invoices/{id}/pdfGETList quotes/api/v1/quotesPOSTCreate a quote/api/v1/quotesGETGet a quote/api/v1/quotes/{id}PATCHUpdate a quote/api/v1/quotes/{id}DELETEDelete a draft quote/api/v1/quotes/{id}POSTMark a quote sent/api/v1/quotes/{id}/sendPOSTMark a quote accepted/api/v1/quotes/{id}/acceptPOSTMark a quote declined/api/v1/quotes/{id}/declinePOSTConvert a quote to an invoice/api/v1/quotes/{id}/convertGETDownload a quote PDF/api/v1/quotes/{id}/pdfGETList credit notes/api/v1/credit-notesPOSTCreate a credit note/api/v1/credit-notesGETGet a credit note/api/v1/credit-notes/{id}POSTIssue a credit note/api/v1/credit-notes/{id}/issuePOSTVoid a credit note/api/v1/credit-notes/{id}/voidPOSTApply credit to an invoice/api/v1/credit-notes/{id}/applyPOSTPay credit back/api/v1/credit-notes/{id}/refundGETDownload a credit note PDF/api/v1/credit-notes/{id}/pdfGETList subscriptions/api/v1/subscriptionsGETGet a subscription/api/v1/subscriptions/{id}POSTPause a subscription/api/v1/subscriptions/{id}/pausePOSTResume a subscription/api/v1/subscriptions/{id}/resumePOSTCancel a subscription/api/v1/subscriptions/{id}/cancelGETList packages/api/v1/packagesPOSTCreate a package/api/v1/packagesGETGet a package/api/v1/packages/{id}PATCHUpdate a package/api/v1/packages/{id}DELETEDisable a package/api/v1/packages/{id}POSTAdd a plan to a package/api/v1/packages/{id}/plansGETList plans (find one by code)/api/v1/plansGETGet a plan/api/v1/plans/{id}PATCHUpdate a plan/api/v1/plans/{id}GETList customer subscriptions/api/v1/customer-subscriptionsPOSTSubscribe a customer to a plan/api/v1/customer-subscriptionsGETGet a customer subscription/api/v1/customer-subscriptions/{id}PATCHUpdate a customer subscription/api/v1/customer-subscriptions/{id}POSTPause a customer subscription/api/v1/customer-subscriptions/{id}/pausePOSTResume a customer subscription/api/v1/customer-subscriptions/{id}/resumePOSTCancel a customer subscription/api/v1/customer-subscriptions/{id}/cancelPOSTChange plan/api/v1/customer-subscriptions/{id}/change-planGETList products/api/v1/productsPOSTCreate a product/api/v1/productsGETGet a product/api/v1/products/{id}PATCHUpdate a product/api/v1/products/{id}GETList EFT orders/api/v1/eft-ordersPOSTCreate an EFT order/api/v1/eft-ordersGETGet an EFT order/api/v1/eft-orders/{id}POSTUpload proof of payment/api/v1/eft-orders/{id}/proofGETDownload a proof of payment/api/v1/eft-orders/{id}/proofs/{proofId}POSTCancel an EFT order/api/v1/eft-orders/{id}/cancelGETList transactions/api/v1/transactionsGETGet a transaction by reference/api/v1/transactions/{reference}GETList receipts/api/v1/receiptsGETGet a receipt/api/v1/receipts/{id}GETList refunds/api/v1/refundsGETGet a refund/api/v1/refunds/{id}GETList payouts/api/v1/payoutsPOSTSchedule a payout/api/v1/payoutsGETGet a payout/api/v1/payouts/{id}POSTCancel a payout/api/v1/payouts/{id}/cancelGETList mandates/api/v1/mandatesPOSTCreate a mandate/api/v1/mandatesGETGet a mandate/api/v1/mandates/{id}PATCHUpdate a mandate/api/v1/mandates/{id}POSTIssue a mandate agreement/api/v1/mandates/{id}/agreementGETList reconciliation runs/api/v1/reconciliation/runsGETGet a reconciliation run/api/v1/reconciliation/runs/{id}GETList statement lines/api/v1/reconciliation/linesGETList Netcash accounts/api/v1/reconciliation/accountsGETList accounting referral links/api/v1/accounting/referral-linksGETGet your organisation and entitlements/api/v1/meGETCheck one entitlement/api/v1/entitlements/{key}POSTPreview a change/api/v1/customer-subscriptions/{id}/preview-changePOSTReactivate a subscription/api/v1/customer-subscriptions/{id}/reactivatePOSTRecord your platform's period (external subscriptions)/api/v1/customer-subscriptions/{id}/sync-periodPOSTAdd credit/api/v1/customer-subscriptions/{id}/creditPOSTDiscount the next renewal/api/v1/customer-subscriptions/{id}/discountDELETECancel a scheduled change/api/v1/customer-subscriptions/{id}/pending-changeGETList items/api/v1/customer-subscriptions/{id}/itemsPOSTAdd an item/api/v1/customer-subscriptions/{id}/itemsPUTReplace the recurring items/api/v1/customer-subscriptions/{id}/itemsPATCHUpdate an item/api/v1/customer-subscriptions/{id}/items/{itemId}DELETERemove an item/api/v1/customer-subscriptions/{id}/items/{itemId}POSTRecord metered usage/api/v1/customer-subscriptions/{id}/items/{itemId}/usageGETList a subscription's invoices/api/v1/customer-subscriptions/{id}/invoicesGETList a subscription's payments/api/v1/customer-subscriptions/{id}/paymentsPOSTChange amount or next charge date/api/v1/subscriptions/{id}/updatePOSTRetry a failed charge/api/v1/subscriptions/{id}/retryGETList charges/api/v1/subscriptions/{id}/chargesGETList migrations/api/v1/subscriptions/migrationsPOSTMigrate legacy subscriptions/api/v1/subscriptions/migrationsGETGet a migration/api/v1/subscriptions/migrations/{id}POSTMigration actions/api/v1/subscriptions/migrations/{id}/{action}
GET/api/v1/payment-links

Returns your organisation's payment links, newest first, each with the payments made through it (up to 50 per link). Filter by externalReference to find the link for one of your orders and discover its payment references.

Query parameters
FieldTypeDescription
externalReferencestring

Only links with exactly this external reference (leading/trailing whitespace ignored).

limitinteger

Maximum number of links to return, 1–100. Invalid or missing values fall back to 20; values out of range are clamped.

≥ 1 · ≤ 100 · default 20

200Matching links.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredPaymentLinkWithPayments[]
Show fields
data fields
FieldTypeDescription
idrequiredstring

Payment link ID.

urlrequiredstring (uri)

Hosted payment page to send to the payer: https://app.centrapoint.co.za/pay/{token}.

titlerequiredstring
descriptionrequiredstring | null
amountrequirednumber

Amount after rounding to 2 decimal places.

currencyrequiredstring

Upper-case ISO 4217 code.

externalReferencerequiredstring | null

Your identifier, as supplied when the link was created.

returnUrlrequiredstring (uri) | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

recurringrequirednull | object
Show fields
recurring fields
FieldTypeDescription
frequencyrequiredstring
amountrequirednumber
singleUserequiredboolean

Whether the link deactivates after its first successful payment.

saveCardrequiredboolean

The link saves the card it is paid with as the customer's default card (since 1.20.0).

activerequiredboolean

False once deactivated (in the dashboard, or after a single-use link is paid).

expiresAtrequiredstring (date-time) | null
paidCountrequiredinteger

Number of successful payments made through the link.

createdAtrequiredstring (date-time)
paymentsrequiredLinkPayment[]

Checkout attempts made through the link, newest first. Each attempt is a transaction with its own reference.

Show fields
payments fields
FieldTypeDescription
referencerequiredstring

Payment reference. Use it with GET /api/v1/transactions/{reference}.

statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountrequirednumber
currencyrequiredstring
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
subscriptionnull | object

The latest subscription started by this link, or null.

Show fields
subscription fields
FieldTypeDescription
idrequiredstring
statusrequiredstring
Example
{
  "data": [
    {
      "id": "cmg1k2x3y0001abcd1234efgh",
      "url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
      "title": "Website hosting - October",
      "description": "Monthly hosting for example.co.za",
      "amount": 499,
      "currency": "ZAR",
      "externalReference": "ORDER-1001",
      "singleUse": true,
      "active": false,
      "expiresAt": "2026-10-31T21:59:59.000Z",
      "paidCount": 1,
      "createdAt": "2026-09-25T08:10:02.114Z",
      "payments": [
        {
          "reference": "CP-20260925-9F3A1C7B",
          "status": "complete",
          "amount": 499,
          "currency": "ZAR",
          "paidAt": "2026-09-25T08:14:03.512Z",
          "createdAt": "2026-09-25T08:12:47.020Z"
        },
        {
          "reference": "CP-20260925-41D07E2A",
          "status": "cancelled",
          "amount": 499,
          "currency": "ZAR",
          "paidAt": null,
          "createdAt": "2026-09-25T08:11:15.873Z"
        }
      ],
      "returnUrl": null,
      "metadata": {},
      "recurring": null,
      "subscription": null
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
curl -X GET "https://app.centrapoint.co.za/api/v1/payment-links?externalReference=ORDER-1001" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"
POST/api/v1/payment-links

Creates a hosted payment link at /pay/{token}. When customerEmail is supplied, the link is attached to the existing customer with that email address in your organisation, or a new customer is created (subject to your plan's customer limit).

Requires the API and Payment links features on your plan, and an account that is not read-only (suspended, cancelled or expired trial).

Pass externalReference (your order ID) so you can later find the link and the payment references made through it with GET /api/v1/payment-links?externalReference=.

Unknown body fields are ignored. This endpoint is not idempotent: retrying a request creates another link.

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

application/json · required

Request body fields
FieldTypeDescription
titlerequiredstring

Shown to the payer. Leading and trailing whitespace is trimmed before the length check.

1–100 chars

descriptionstring

Optional longer text shown under the title on the payment page.

max 255 chars

amountrequirednumber

Amount in major units (e.g. 499.00 rand). Rounded to 2 decimal places. Gateways may enforce their own minimums or whole-unit amounts.

> 0 · ≤ 10 000 000

currencystring

ISO 4217 currency code, upper-cased by the server. Must be a valid ISO 4217 code and accepted by at least one of your enabled checkout gateways (or, for once-off links, by your Manual EFT gateway); otherwise the request fails with 400 invalid_request.

default "ZAR"

externalReferencestring

Your own identifier for this link, e.g. your order or invoice number. Trimmed before validation. Not required to be unique. Use it with GET /api/v1/payment-links?externalReference= to find the link and its payment references later.

1–100 chars

returnUrlstring (uri)

Where to send the payer after a final outcome. Must be https and on an origin allow-listed under Settings → API keys → Allowed return URLs. CentraPoint appends reference and status (complete, failed or cancelled) query parameters. Never trust the redirect: confirm server-side.

max 1000 chars

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerIdstring

Attach an existing customer (takes precedence over customerEmail).

recurringobject

Start a gateway-managed subscription when the link is paid. Requires a plan with recurring billing and an enabled gateway that supports it (PayFast, Netcash Pay Now); only such gateways are offered to the payer. Can be combined with invoiceId when the invoice has a billing period (see invoiceId).

Show fields
recurring fields
FieldTypeDescription
frequencyrequiredstring

One of: monthly, quarterly, biannually, annually

amountnumber

Amount of each later collection. Defaults to the link amount.

> 0 · ≤ 10 000 000

productIdstring

ID of a product in your organisation. Recurring products start a gateway-managed subscription at checkout (plan and gateway permitting).

invoiceIdstring

ID of an invoice in your organisation. Successful payments are applied to the invoice. With recurring (or a recurring product) the invoice must have a billing period: the first payment settles it and every later payment of the subscription (each renewal, a retry of a failed renewal, the payment of a replacement checkout) creates and pays a new invoice for the next period (amount = invoice balance, recurring.amount = invoice total, same currency and customer; the subscription's amount cannot change later); otherwise 400. A payment that cannot be invoiced is left unallocated and reported to your staff (audit log and notification).

customerEmailstring (email)

Attach the link to a customer. Matched case-insensitively against existing customers; a new customer is created if none exists.

customerFirstNamestring

Used only when a new customer is created. Defaults to the part of the email before @.

max 100 chars

customerLastNamestring

Used only when a new customer is created.

max 100 chars

singleUseboolean

When true, the link is deactivated after its first successful payment.

default true

expiresAtstring (date-time)

ISO 8601 timestamp with Z or a UTC offset (e.g. 2026-10-31T23:59:59+02:00), including seconds. Must be in the future and at most 1 year ahead. After this moment the link cannot be paid.

saveCardboolean

Save the card the customer pays this link with as their default card (gateways that save cards, e.g. Netcash Pay Now). Ignored since 1.21.0: saved cards are no longer charged or saved. Bill subscriptions with a recurring link (recurring): a Netcash Pay Now card subscription that Netcash charges each period.

default false

201Payment link created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
idrequiredstring

Payment link ID.

urlrequiredstring (uri)

Hosted payment page to send to the payer: https://app.centrapoint.co.za/pay/{token}.

titlerequiredstring
descriptionrequiredstring | null
amountrequirednumber

Amount after rounding to 2 decimal places.

currencyrequiredstring

Upper-case ISO 4217 code.

externalReferencerequiredstring | null

Your identifier, as supplied when the link was created.

returnUrlrequiredstring (uri) | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

recurringrequirednull | object
Show fields
recurring fields
FieldTypeDescription
frequencyrequiredstring
amountrequirednumber
singleUserequiredboolean

Whether the link deactivates after its first successful payment.

saveCardrequiredboolean

The link saves the card it is paid with as the customer's default card (since 1.20.0).

activerequiredboolean

False once deactivated (in the dashboard, or after a single-use link is paid).

expiresAtrequiredstring (date-time) | null
paidCountrequiredinteger

Number of successful payments made through the link.

createdAtrequiredstring (date-time)
Example
{
  "id": "cmg1k2x3y0001abcd1234efgh",
  "url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "title": "Website hosting - October",
  "description": "Monthly hosting for example.co.za",
  "amount": 499,
  "currency": "ZAR",
  "externalReference": "ORDER-1001",
  "singleUse": true,
  "active": true,
  "expiresAt": "2026-10-31T21:59:59.000Z",
  "paidCount": 0,
  "createdAt": "2026-09-25T08:10:02.114Z",
  "returnUrl": "https://shop.example.co.za/checkout/done",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "recurring": null
}
400The body failed validation (`issues` lists each problem), or a business rule failed: unknown product/invoice, invalid or unsupported currency, or `expiresAt` not in the future / more than 1 year ahead.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Validation failure
{
  "error": "invalid_request",
  "message": "Invalid body",
  "issues": [
    {
      "origin": "number",
      "code": "too_small",
      "minimum": 0,
      "inclusive": false,
      "path": [
        "amount"
      ],
      "message": "Too small: expected number to be >0"
    }
  ]
}
Unknown product
{
  "error": "invalid_request",
  "message": "Product not found"
}
Currency not accepted
{
  "error": "invalid_request",
  "message": "None of your enabled payment gateways accept USD. Enable a gateway that supports USD first."
}
Expiry in the past
{
  "error": "invalid_request",
  "message": "expiresAt must be in the future"
}
returnUrl origin not allowed
{
  "error": "invalid_request",
  "message": "returnUrl origin https://shop.example.co.za is not allowed - add it under Settings > API keys > Allowed return URLs"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Your plan does not include the API or payment links (`plan_restricted`), a plan quota such as the customer limit was reached (`plan_limit`), or the account is read-only (`account_restricted`).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
planRestricted
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
planLimit
{
  "error": "plan_limit",
  "message": "Customers limit reached (2000/2000) on the Growth plan. Upgrade under Settings > Billing."
}
accountRestricted
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
413Request body larger than 100 000 characters.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Request body too large"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
curl -X POST "https://app.centrapoint.co.za/api/v1/payment-links" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pro plan",
    "amount": 499,
    "externalReference": "SUB-ACME-PRO",
    "customerId": "cmg2c0s7t0003cust0001abcd",
    "recurring": {
      "frequency": "monthly"
    },
    "singleUse": true
  }'
GET/api/v1/payment-links/{id}

Returns one payment link in your organisation with the payments made through it (newest first, up to 100).

Path parameters
FieldTypeDescription
idrequiredstring

Payment link ID returned when the link was created.

200The payment link.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring

Payment link ID.

urlrequiredstring (uri)

Hosted payment page to send to the payer: https://app.centrapoint.co.za/pay/{token}.

titlerequiredstring
descriptionrequiredstring | null
amountrequirednumber

Amount after rounding to 2 decimal places.

currencyrequiredstring

Upper-case ISO 4217 code.

externalReferencerequiredstring | null

Your identifier, as supplied when the link was created.

returnUrlrequiredstring (uri) | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

recurringrequirednull | object
Show fields
recurring fields
FieldTypeDescription
frequencyrequiredstring
amountrequirednumber
singleUserequiredboolean

Whether the link deactivates after its first successful payment.

saveCardrequiredboolean

The link saves the card it is paid with as the customer's default card (since 1.20.0).

activerequiredboolean

False once deactivated (in the dashboard, or after a single-use link is paid).

expiresAtrequiredstring (date-time) | null
paidCountrequiredinteger

Number of successful payments made through the link.

createdAtrequiredstring (date-time)
paymentsrequiredLinkPayment[]

Checkout attempts made through the link, newest first. Each attempt is a transaction with its own reference.

Show fields
payments fields
FieldTypeDescription
referencerequiredstring

Payment reference. Use it with GET /api/v1/transactions/{reference}.

statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountrequirednumber
currencyrequiredstring
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
subscriptionnull | object

The latest subscription started by this link, or null.

Show fields
subscription fields
FieldTypeDescription
idrequiredstring
statusrequiredstring
Example
{
  "id": "cmg1k2x3y0001abcd1234efgh",
  "url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "title": "Website hosting - October",
  "description": "Monthly hosting for example.co.za",
  "amount": 499,
  "currency": "ZAR",
  "externalReference": "ORDER-1001",
  "singleUse": true,
  "active": false,
  "expiresAt": "2026-10-31T21:59:59.000Z",
  "paidCount": 1,
  "createdAt": "2026-09-25T08:10:02.114Z",
  "payments": [
    {
      "reference": "CP-20260925-9F3A1C7B",
      "status": "complete",
      "amount": 499,
      "currency": "ZAR",
      "paidAt": "2026-09-25T08:14:03.512Z",
      "createdAt": "2026-09-25T08:12:47.020Z"
    },
    {
      "reference": "CP-20260925-41D07E2A",
      "status": "cancelled",
      "amount": 499,
      "currency": "ZAR",
      "paidAt": null,
      "createdAt": "2026-09-25T08:11:15.873Z"
    }
  ],
  "returnUrl": null,
  "metadata": {},
  "recurring": null,
  "subscription": null
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No payment link with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Payment link not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
curl -X GET "https://app.centrapoint.co.za/api/v1/payment-links/cmg1k2x3y0001abcd1234efgh" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List checkout sessions#

GET/api/v1/checkout-sessions

Newest first.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

Filter by reported status: expired also matches pending and failed sessions past expiresAt; pending and failed only match sessions that have not expired.

One of: pending, completed, failed, expired

customerIdstring

Filter by customer.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Sessions.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredCheckoutSession[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: checkout_session

statusrequiredstring

expired: not completed and past expiresAt. A payment that completes later still moves the session to completed.

One of: pending, completed, failed, expired

sourcerequiredstring

api: created with this API; hosted: created by a payer on a shared checkout page.

One of: api, hosted

checkoutUrlrequiredstring | null

Hosted checkout URL while the session is pending or failed and not expired (null for hosted sessions).

packageIdrequiredstring | null
planIdrequiredstring | null

Preselected plan.

productIdrequiredstring | null
customerIdrequiredstring | null

Set once the payer's details are known.

subscriptionIdrequiredstring | null

Customer subscription created by the checkout.

couponCoderequiredstring | null
returnUrlrequiredstring | null
prefillrequiredobject
Show fields
prefill fields
FieldTypeDescription
emailstring
firstNamestring
lastNamestring
phonestring
companystring
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

transactionrequiredobject | null
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
statusstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountnumber
currencystring
discountAmountnumber | null
taxAmountnumber | null
paidAtstring (date-time) | null
expiresAtrequiredstring (date-time)
usedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg5k1s2e0010cks0001abcd",
      "object": "checkout_session",
      "status": "pending",
      "source": "api",
      "checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "planId": "cmg4p1a2b0002pln0001abcd",
      "productId": null,
      "customerId": null,
      "subscriptionId": null,
      "couponCode": "WELCOME10",
      "returnUrl": "https://www.example.co.za/thanks",
      "prefill": {
        "email": "[email protected]",
        "firstName": "Thandi",
        "lastName": "Nkosi"
      },
      "metadata": {
        "signupId": "SU-9921"
      },
      "transaction": null,
      "expiresAt": "2026-09-29T08:30:00.000Z",
      "usedAt": null,
      "createdAt": "2026-09-28T08:30:00.000Z",
      "updatedAt": "2026-09-28T08:30:00.000Z"
    }
  ]
}
400Invalid status.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of pending, completed, failed, expired"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a checkout session#

POST/api/v1/checkout-sessions

Returns a pre-filled hosted checkout URL for a package (optionally with a preselected plan) or a product, valid for 24 hours. Follow the outcome with GET /api/v1/checkout-sessions/{id} or the checkout.completed / checkout.failed webhooks.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
packageIdstring

max 40 chars

planIdstring

Preselects a plan; the package is derived when packageId is omitted. Plans with a call to action or contact option can't be sold through checkout.

max 40 chars

productIdstring

max 40 chars

returnUrlstring

https URL whose origin is allow-listed under Settings → API keys → Allowed return URLs.

max 1000 chars

customerobject

Payer details to pre-fill.

Show fields
customer fields
FieldTypeDescription
emailstring

max 200 chars

firstNamestring

max 100 chars

lastNamestring

max 100 chars

phonestring

max 30 chars

companystring

max 200 chars

companyNamestring

Alias of company.

max 200 chars

clientobject

Alias of customer.

Show fields
client fields
FieldTypeDescription
emailstring

max 200 chars

firstNamestring

max 100 chars

lastNamestring

max 100 chars

phonestring

max 30 chars

companystring

max 200 chars

companyNamestring

Alias of company.

max 200 chars

couponCodestring

Must be an enabled coupon; needs Coupons in your plan.

1–50 chars

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

Responses#

201The session.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: checkout_session

statusrequiredstring

expired: not completed and past expiresAt. A payment that completes later still moves the session to completed.

One of: pending, completed, failed, expired

sourcerequiredstring

api: created with this API; hosted: created by a payer on a shared checkout page.

One of: api, hosted

checkoutUrlrequiredstring
packageIdrequiredstring | null
planIdrequiredstring | null

Preselected plan.

productIdrequiredstring | null
customerIdrequiredstring | null

Set once the payer's details are known.

subscriptionIdrequiredstring | null

Customer subscription created by the checkout.

couponCoderequiredstring | null
returnUrlrequiredstring | null
prefillrequiredobject
Show fields
prefill fields
FieldTypeDescription
emailstring
firstNamestring
lastNamestring
phonestring
companystring
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

transactionrequiredobject | null
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
statusstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountnumber
currencystring
discountAmountnumber | null
taxAmountnumber | null
paidAtstring (date-time) | null
expiresAtrequiredstring (date-time)
usedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
sessionIdrequiredstring

Same as id.

Example
{
  "id": "cmg5k1s2e0010cks0001abcd",
  "object": "checkout_session",
  "status": "pending",
  "source": "api",
  "checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
  "packageId": "cmg4p1a2b0001pkg0001abcd",
  "planId": "cmg4p1a2b0002pln0001abcd",
  "productId": null,
  "customerId": null,
  "subscriptionId": null,
  "couponCode": "WELCOME10",
  "returnUrl": "https://www.example.co.za/thanks",
  "prefill": {
    "email": "[email protected]",
    "firstName": "Thandi",
    "lastName": "Nkosi"
  },
  "metadata": {
    "signupId": "SU-9921"
  },
  "transaction": null,
  "expiresAt": "2026-09-29T08:30:00.000Z",
  "usedAt": null,
  "createdAt": "2026-09-28T08:30:00.000Z",
  "updatedAt": "2026-09-28T08:30:00.000Z",
  "sessionId": "cmg5k1s2e0010cks0001abcd"
}
400Validation failed: nothing or both kinds of target, unknown/disabled package, plan or product, returnUrl not https or not allow-listed, invalid coupon.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "returnUrl origin https://www.example.co.za is not allowed - add it under Settings > API keys > Allowed return URLs"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403`plan_restricted`: no REST API. `plan_limit`: a package checkout needs Recurring billing, a product checkout Payment links. `account_restricted`: read-only account.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_limit",
  "message": "Recurring card billing is not included in the Starter plan. Upgrade under Settings > Billing."
}
409Idempotency-Key reused with a different body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/checkout-sessions" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "cmg4p1a2b0002pln0001abcd",
    "returnUrl": "https://www.example.co.za/thanks",
    "customer": {
      "email": "[email protected]",
      "firstName": "Thandi",
      "lastName": "Nkosi"
    },
    "couponCode": "WELCOME10",
    "metadata": {
      "signupId": "SU-9921"
    }
  }'

Get a checkout session#

GET/api/v1/checkout-sessions/{id}

Status, the payment (reference, status, amounts) and the resulting subscription.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The session.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: checkout_session

statusrequiredstring

expired: not completed and past expiresAt. A payment that completes later still moves the session to completed.

One of: pending, completed, failed, expired

sourcerequiredstring

api: created with this API; hosted: created by a payer on a shared checkout page.

One of: api, hosted

checkoutUrlrequiredstring | null

Hosted checkout URL while the session is pending or failed and not expired (null for hosted sessions).

packageIdrequiredstring | null
planIdrequiredstring | null

Preselected plan.

productIdrequiredstring | null
customerIdrequiredstring | null

Set once the payer's details are known.

subscriptionIdrequiredstring | null

Customer subscription created by the checkout.

couponCoderequiredstring | null
returnUrlrequiredstring | null
prefillrequiredobject
Show fields
prefill fields
FieldTypeDescription
emailstring
firstNamestring
lastNamestring
phonestring
companystring
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

transactionrequiredobject | null
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
statusstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountnumber
currencystring
discountAmountnumber | null
taxAmountnumber | null
paidAtstring (date-time) | null
expiresAtrequiredstring (date-time)
usedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg5k1s2e0010cks0001abcd",
  "object": "checkout_session",
  "status": "pending",
  "source": "api",
  "checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
  "packageId": "cmg4p1a2b0001pkg0001abcd",
  "planId": "cmg4p1a2b0002pln0001abcd",
  "productId": null,
  "customerId": null,
  "subscriptionId": null,
  "couponCode": "WELCOME10",
  "returnUrl": "https://www.example.co.za/thanks",
  "prefill": {
    "email": "[email protected]",
    "firstName": "Thandi",
    "lastName": "Nkosi"
  },
  "metadata": {
    "signupId": "SU-9921"
  },
  "transaction": null,
  "expiresAt": "2026-09-29T08:30:00.000Z",
  "usedAt": null,
  "createdAt": "2026-09-28T08:30:00.000Z",
  "updatedAt": "2026-09-28T08:30:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No session with this ID.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Checkout session not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List coupons#

GET/api/v1/coupons

Newest first, with redemption counts.

Query parameters#

Query parameters
FieldTypeDescription
codestring

Exact code (case-insensitive).

enabledstring

Only enabled/disabled coupons.

One of: true, false

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Coupons.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredCoupon[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: coupon

coderequiredstring
descriptionrequiredstring | null
typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

currencyrequiredstring | null

Required for fixed coupons.

appliesTorequiredstring

One of: any, product, subscription

productIdsrequiredstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsrequiredstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationrequiredstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

durationCyclesrequiredinteger | null

Required for repeating.

validFromrequiredstring (date-time) | null
validTorequiredstring (date-time) | null

After validFrom.

maxRedemptionsrequiredinteger | null
maxPerCustomerrequiredinteger | null
minAmountrequirednumber | null
enabledrequiredboolean
redemptionsrequiredobject

Usage counts: redeemed, and pending (checkouts in progress, holding a slot for 2 hours). Always this object.

Show fields
redemptions fields
FieldTypeDescription
redeemedrequiredinteger
pendingrequiredinteger
recentRedemptionsCouponRedemption[]

Only with ?include=redemptions on GET /api/v1/coupons/{id}: the latest 100 redemptions, newest first.

Show fields
recentRedemptions fields
FieldTypeDescription
idstring
statusstring
discountAmountnumber
customerIdstring | null
subscriptionIdstring | null
transactionReferencestring | null
createdAtstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg5c0u1p0011cpn0001abcd",
      "object": "coupon",
      "code": "WELCOME10",
      "description": "10% off the first month",
      "type": "percent",
      "value": 10,
      "currency": null,
      "appliesTo": "any",
      "productIds": [],
      "planIds": [],
      "duration": "once",
      "durationCycles": null,
      "validFrom": null,
      "validTo": "2026-12-31T21:59:59.000Z",
      "maxRedemptions": 500,
      "maxPerCustomer": 1,
      "minAmount": null,
      "enabled": true,
      "redemptions": {
        "redeemed": 12,
        "pending": 1
      },
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Coupons are not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a coupon#

POST/api/v1/coupons

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
coderequiredstring

3–50 letters, digits, - or _; stored upper-case.

descriptionstring | null

max 500 chars

typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

> 0 · ≤ 1 000 000

currencystring | null

Required for fixed coupons.

appliesTostring

One of: any, product, subscription

default "any"

productIdsstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

default "once"

durationCyclesinteger | null

Required for repeating.

≥ 1 · ≤ 120

validFromstring (date-time) | null
validTostring (date-time) | null

After validFrom.

maxRedemptionsinteger | null

≥ 1 · ≤ 10 000 000

maxPerCustomerinteger | null

≥ 1 · ≤ 10 000

minAmountnumber | null

≥ 0 · ≤ 100 000 000

enabledboolean

default true

Responses#

201The coupon.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: coupon

coderequiredstring
descriptionrequiredstring | null
typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

currencyrequiredstring | null

Required for fixed coupons.

appliesTorequiredstring

One of: any, product, subscription

productIdsrequiredstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsrequiredstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationrequiredstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

durationCyclesrequiredinteger | null

Required for repeating.

validFromrequiredstring (date-time) | null
validTorequiredstring (date-time) | null

After validFrom.

maxRedemptionsrequiredinteger | null
maxPerCustomerrequiredinteger | null
minAmountrequirednumber | null
enabledrequiredboolean
redemptionsrequiredobject

Usage counts: redeemed, and pending (checkouts in progress, holding a slot for 2 hours). Always this object.

Show fields
redemptions fields
FieldTypeDescription
redeemedrequiredinteger
pendingrequiredinteger
recentRedemptionsCouponRedemption[]

Only with ?include=redemptions on GET /api/v1/coupons/{id}: the latest 100 redemptions, newest first.

Show fields
recentRedemptions fields
FieldTypeDescription
idstring
statusstring
discountAmountnumber
customerIdstring | null
subscriptionIdstring | null
transactionReferencestring | null
createdAtstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg5c0u1p0011cpn0001abcd",
  "object": "coupon",
  "code": "WELCOME10",
  "description": "10% off the first month",
  "type": "percent",
  "value": 10,
  "currency": null,
  "appliesTo": "any",
  "productIds": [],
  "planIds": [],
  "duration": "once",
  "durationCycles": null,
  "validFrom": null,
  "validTo": "2026-12-31T21:59:59.000Z",
  "maxRedemptions": 500,
  "maxPerCustomer": 1,
  "minAmount": null,
  "enabled": true,
  "redemptions": {
    "redeemed": 0,
    "pending": 0
  },
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed (code format, percentage over 100, fixed without currency, repeating without durationCycles, validTo before validFrom, duplicate code…).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A fixed discount needs a currency"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Coupons are not included in your plan"
}
409Idempotency-Key reused with a different body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/coupons" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "description": "10% off the first month",
    "type": "percent",
    "value": 10,
    "duration": "once",
    "validTo": "2026-12-31T23:59:59+02:00",
    "maxRedemptions": 500,
    "maxPerCustomer": 1
  }'

Validate a coupon#

POST/api/v1/coupons/validate

Would this code apply to a product or plan (for this customer)? Nothing is reserved or redeemed. An unusable code is a 200 with valid: false. The Idempotency-Key header is not used.

Request body#

application/json · required

Request body fields
FieldTypeDescription
coderequiredstring

1–50 chars

productIdstring

max 40 chars

planIdstring

max 40 chars

amountnumber

Price before discount and tax; default the product/plan price.

> 0 · ≤ 100 000 000

currencystring

Default the product/plan currency.

exactly 3 chars

customerIdstring

For per-customer limits.

max 40 chars

customerEmailstring (email)

For per-customer limits.

max 200 chars

Responses#

200The result.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
validrequiredboolean
discountnumber

valid: discount on amount.

amountnumber
totalnumber

amount − discount.

currencystring
couponCoupon
Show fields
coupon fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: coupon

coderequiredstring
descriptionrequiredstring | null
typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

currencyrequiredstring | null

Required for fixed coupons.

appliesTorequiredstring

One of: any, product, subscription

productIdsrequiredstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsrequiredstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationrequiredstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

durationCyclesrequiredinteger | null

Required for repeating.

validFromrequiredstring (date-time) | null
validTorequiredstring (date-time) | null

After validFrom.

maxRedemptionsrequiredinteger | null
maxPerCustomerrequiredinteger | null
minAmountrequirednumber | null
enabledrequiredboolean
redemptionsrequiredobject

Usage counts: redeemed, and pending (checkouts in progress, holding a slot for 2 hours). Always this object.

Show fields
redemptions fields
FieldTypeDescription
redeemedrequiredinteger
pendingrequiredinteger
recentRedemptionsCouponRedemption[]

Only with ?include=redemptions on GET /api/v1/coupons/{id}: the latest 100 redemptions, newest first.

Show fields
recentRedemptions fields
FieldTypeDescription
idstring
statusstring
discountAmountnumber
customerIdstring | null
subscriptionIdstring | null
transactionReferencestring | null
createdAtstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
reasonstring

invalid: why.

One of: not_found, disabled, not_started, expired, wrong_kind, not_applicable, currency_mismatch, below_minimum, exhausted, customer_limit, recurring_duration, no_discount

messagestring

invalid: customer-safe message.

valid
{
  "valid": true,
  "discount": 49.9,
  "amount": 499,
  "total": 449.1,
  "currency": "ZAR",
  "coupon": {
    "id": "cmg5c0u1p0011cpn0001abcd",
    "object": "coupon",
    "code": "WELCOME10",
    "description": "10% off the first month",
    "type": "percent",
    "value": 10,
    "currency": null,
    "appliesTo": "any",
    "productIds": [],
    "planIds": [],
    "duration": "once",
    "durationCycles": null,
    "validFrom": null,
    "validTo": "2026-12-31T21:59:59.000Z",
    "maxRedemptions": 500,
    "maxPerCustomer": 1,
    "minAmount": null,
    "enabled": true,
    "createdAt": "2026-09-28T08:00:00.000Z",
    "updatedAt": "2026-09-28T08:00:00.000Z"
  }
}
invalid
{
  "valid": false,
  "reason": "expired",
  "message": "This coupon has expired"
}
400Validation failed (e.g. not exactly one of productId/planId).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Coupons are not included in your plan"
}
404Product or plan not found.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Plan not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/coupons/validate" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "planId": "cmg4p1a2b0002pln0001abcd",
    "customerEmail": "[email protected]"
  }'

Get a coupon#

GET/api/v1/coupons/{id}

?include=redemptions adds recentRedemptions: the latest 100 redemptions (id, status, discountAmount, customerId, subscriptionId, transactionReference, createdAt). redemptions stays the counts object.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Query parameters#

Query parameters
FieldTypeDescription
includestring

redemptions.

One of: redemptions

Responses#

200The coupon.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: coupon

coderequiredstring
descriptionrequiredstring | null
typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

currencyrequiredstring | null

Required for fixed coupons.

appliesTorequiredstring

One of: any, product, subscription

productIdsrequiredstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsrequiredstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationrequiredstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

durationCyclesrequiredinteger | null

Required for repeating.

validFromrequiredstring (date-time) | null
validTorequiredstring (date-time) | null

After validFrom.

maxRedemptionsrequiredinteger | null
maxPerCustomerrequiredinteger | null
minAmountrequirednumber | null
enabledrequiredboolean
redemptionsrequiredobject

Usage counts: redeemed, and pending (checkouts in progress, holding a slot for 2 hours). Always this object.

Show fields
redemptions fields
FieldTypeDescription
redeemedrequiredinteger
pendingrequiredinteger
recentRedemptionsCouponRedemption[]

Only with ?include=redemptions on GET /api/v1/coupons/{id}: the latest 100 redemptions, newest first.

Show fields
recentRedemptions fields
FieldTypeDescription
idstring
statusstring
discountAmountnumber
customerIdstring | null
subscriptionIdstring | null
transactionReferencestring | null
createdAtstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg5c0u1p0011cpn0001abcd",
  "object": "coupon",
  "code": "WELCOME10",
  "description": "10% off the first month",
  "type": "percent",
  "value": 10,
  "currency": null,
  "appliesTo": "any",
  "productIds": [],
  "planIds": [],
  "duration": "once",
  "durationCycles": null,
  "validFrom": null,
  "validTo": "2026-12-31T21:59:59.000Z",
  "maxRedemptions": 500,
  "maxPerCustomer": 1,
  "minAmount": null,
  "enabled": true,
  "redemptions": {
    "redeemed": 12,
    "pending": 1
  },
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Coupons are not included in your plan"
}
404No coupon with this ID.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Coupon not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a coupon#

PATCH/api/v1/coupons/{id}

Any create field, validated after merging with the stored coupon. Send {"enabled": false} to disable; there is no DELETE. The Idempotency-Key header is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
codestring

3–50 letters, digits, - or _; stored upper-case.

descriptionstring | null

max 500 chars

typestring

One of: percent, fixed

valuenumber

Percentage (at most 100) or fixed amount.

> 0 · ≤ 1 000 000

currencystring | null

Required for fixed coupons.

appliesTostring

One of: any, product, subscription

default "any"

productIdsstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

default "once"

durationCyclesinteger | null

Required for repeating.

≥ 1 · ≤ 120

validFromstring (date-time) | null
validTostring (date-time) | null

After validFrom.

maxRedemptionsinteger | null

≥ 1 · ≤ 10 000 000

maxPerCustomerinteger | null

≥ 1 · ≤ 10 000

minAmountnumber | null

≥ 0 · ≤ 100 000 000

enabledboolean

default true

Responses#

200The updated coupon.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: coupon

coderequiredstring
descriptionrequiredstring | null
typerequiredstring

One of: percent, fixed

valuerequirednumber

Percentage (at most 100) or fixed amount.

currencyrequiredstring | null

Required for fixed coupons.

appliesTorequiredstring

One of: any, product, subscription

productIdsrequiredstring[]

Limit to these products (empty = all). IDs not in your organisation are dropped.

planIdsrequiredstring[]

Limit to these plans (empty = all). IDs not in your organisation are dropped.

durationrequiredstring

For subscriptions: first charge only, durationCycles charges, or every charge.

One of: once, repeating, forever

durationCyclesrequiredinteger | null

Required for repeating.

validFromrequiredstring (date-time) | null
validTorequiredstring (date-time) | null

After validFrom.

maxRedemptionsrequiredinteger | null
maxPerCustomerrequiredinteger | null
minAmountrequirednumber | null
enabledrequiredboolean
redemptionsrequiredobject

Usage counts: redeemed, and pending (checkouts in progress, holding a slot for 2 hours). Always this object.

Show fields
redemptions fields
FieldTypeDescription
redeemedrequiredinteger
pendingrequiredinteger
recentRedemptionsCouponRedemption[]

Only with ?include=redemptions on GET /api/v1/coupons/{id}: the latest 100 redemptions, newest first.

Show fields
recentRedemptions fields
FieldTypeDescription
idstring
statusstring
discountAmountnumber
customerIdstring | null
subscriptionIdstring | null
transactionReferencestring | null
createdAtstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg5c0u1p0011cpn0001abcd",
  "object": "coupon",
  "code": "WELCOME10",
  "description": "10% off the first month",
  "type": "percent",
  "value": 10,
  "currency": null,
  "appliesTo": "any",
  "productIds": [],
  "planIds": [],
  "duration": "once",
  "durationCycles": null,
  "validFrom": null,
  "validTo": "2026-12-31T21:59:59.000Z",
  "maxRedemptions": 500,
  "maxPerCustomer": 1,
  "minAmount": null,
  "enabled": false,
  "redemptions": {
    "redeemed": 12,
    "pending": 1
  },
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A percentage cannot be more than 100"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Coupons are not included in your plan"
}
404No coupon with this ID.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Coupon not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/coupons/cmg5c0u1p0011cpn0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

List customers#

GET/api/v1/customers

Newest first, keyset paginated (limit, startingAfter; the response has hasMore and nextCursor). Filters combine.

Query parameters#

Query parameters
FieldTypeDescription
qstring

Search (up to 100 characters): every word must appear (case-insensitive) in the first or last name, company, email, billing email, accountCode or externalReference.

max 100 chars

externalReferencestring

Exact match on your customer ID.

emailstring

Exact match (case-insensitive).

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200Customers.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredCustomer[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg2c0s7t0003cust0001abcd",
      "accountCode": "CUS-00042",
      "externalReference": "CRM-1001",
      "email": "[email protected]",
      "firstName": "Thandi",
      "lastName": "Nkosi",
      "company": "Nkosi Trading (Pty) Ltd",
      "vatNumber": "4123456789",
      "phone": "+27821234567",
      "address": "12 Long Street, Cape Town, 8001",
      "active": true,
      "metadata": {
        "crmId": "0061x00000AbCdE"
      },
      "createdAt": "2026-09-25T08:00:00.000Z",
      "updatedAt": "2026-09-25T08:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400`q` longer than 100 characters, or `startingAfter` is not an id from this list.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "startingAfter is not a valid id"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access (or the feature) is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create or upsert a customer#

POST/api/v1/customers

Without externalReference: creates a customer (201). With externalReference: upsert keyed on it — updates the customer with that reference (200), otherwise adopts an existing customer with the same email and no reference (200), otherwise creates one (201). Available on any plan with API access; creating counts towards your customer limit.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
externalReferencestring

Your ID. When set, the request is an upsert keyed on it.

1–190 chars

emailrequiredstring (email)

Stored lower-cased.

max 200 chars

firstNamerequiredstring

1–100 chars

lastNamestring | null

max 100 chars

companystring | null

max 200 chars

vatNumberstring | null

max 30 chars

phonestring | null

max 30 chars

addressstring | null

max 1000 chars

metadataMetadataInput | null
contactTypestring

Default individual on create.

One of: individual, company

billingEmailstring (email) | null

Separate billing address. Subscription emails are sent here instead of email, and it is printed on invoice and statement PDFs. email stays the customer's sign-in address (customer portal). Stored in lower case; null clears it.

max 320 chars

Responses#

200Existing customer updated (upsert).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
201Customer created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
400Validation failed or invalid metadata.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body",
  "issues": [
    {
      "code": "invalid_format",
      "format": "email",
      "path": [
        "email"
      ],
      "message": "Invalid email address"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API, customer limit reached (`plan_limit`), or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_limit",
  "message": "Customers limit reached (2000/2000) on the Growth plan. Upgrade under Settings > Billing."
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customers" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "CRM-1001",
    "email": "[email protected]",
    "firstName": "Thandi",
    "lastName": "Nkosi",
    "company": "Nkosi Trading (Pty) Ltd",
    "vatNumber": "4123456789",
    "phone": "+27821234567",
    "metadata": {
      "crmId": "0061x00000AbCdE"
    }
  }'

Look up a customer#

GET/api/v1/customers/lookup

Exact match on exactly one of email, externalReference or accountCode. Returns the customer, or 404. When several customers share an email, the oldest is returned.

Query parameters#

Query parameters
FieldTypeDescription
emailstring

Exact match, case-insensitive (up to 200 characters).

externalReferencestring

Exact match (up to 190 characters).

accountCodestring

Exact match, e.g. CUS-00042 (up to 50 characters).

Responses#

200The customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
400None or more than one lookup key, or a value too long.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Provide exactly one of email, externalReference or accountCode"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No matching customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customers/lookup?email=thandi%40example.co.za" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a customer#

GET/api/v1/customers/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access (or the feature) is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a customer#

PATCH/api/v1/customers/{id}

Partial update. Omitted fields are unchanged; null clears optional fields; metadata replaces the whole map. Unknown fields are rejected. Idempotency-Key is not used (PATCH is naturally repeatable).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
externalReferencestring | null

Must not be used by another customer.

1–190 chars

emailstring (email)

Stored lower-cased.

max 200 chars

firstNamestring

1–100 chars

lastNamestring | null

max 100 chars

companystring | null

max 200 chars

vatNumberstring | null

max 30 chars

phonestring | null

max 30 chars

addressstring | null

max 1000 chars

metadataMetadataInput | null
activeboolean
contactTypestring

Default individual on create.

One of: individual, company

billingEmailstring (email) | null

Separate billing address. Subscription emails are sent here instead of email, and it is printed on invoice and statement PDFs. email stays the customer's sign-in address (customer portal). Stored in lower case; null clears it.

max 320 chars

Responses#

200Updated customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
accountCoderequiredstring

Customer account code assigned by CentraPoint.

externalReferencerequiredstring | null

Your ID for the customer.

contactTyperequiredstring

One of: individual, company

emailrequiredstring
billingEmailrequiredstring | null

Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs.

firstNamerequiredstring
lastNamerequiredstring | null
companyrequiredstring | null
vatNumberrequiredstring | null
phonerequiredstring | null
addressrequiredstring | null
activerequiredboolean
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
400Validation failed, unknown field, or externalReference used by another customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Another customer already has that externalReference"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+27829876543",
    "company": null,
    "active": true
  }'
POST/api/v1/customers/{id}/portal-link

Default (no body, {} or { "email": true }): emails the customer the portal sign-in page and returns its URL (sent: true). { "email": false, "expiresInMinutes"?, "section"? }: sends nothing and returns a single-use sign-in URL (sent: false, expiresAt) that signs the customer straight in to the portal, valid 15 minutes by default (at most 1440). Create it when your signed-in user clicks through and redirect them; treat it as a secret. Not idempotent (the Idempotency-Key header is ignored).

Path parameters
FieldTypeDescription
idrequiredstring

application/json

Request body fields
FieldTypeDescription
emailboolean

false: create a single-use sign-in link instead of emailing the customer.

default true

expiresInMinutesinteger

Sign-in links only (email: false).

≥ 1 · ≤ 1 440 · default 15

sectionstring

Sign-in links only: portal page to open after sign-in (default the overview).

One of: invoices, payments, subscriptions, statement, payment-methods, profile

200The link was emailed (`sent: true`), or the sign-in link was created (`sent: false`).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: portal_link

customerIdrequiredstring
urlrequiredstring

Emailed: the portal sign-in page. email: false: a single-use sign-in URL that logs the customer in; treat it as a secret.

sentrequiredboolean

true: the portal link was emailed (url is the portal sign-in page). false: a single-use sign-in link was created (email: false) and nothing was emailed.

expiresAtstring (date-time)

Sign-in links only: when the link stops working (it also stops once used).

Emailed
{
  "object": "portal_link",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "url": "https://app.centrapoint.co.za/portal/acme",
  "sent": true
}
Sign-in link (email: false)
{
  "object": "portal_link",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "url": "https://app.centrapoint.co.za/api/portal/auth/acme/link?token=q3Jx…&next=invoices",
  "sent": false,
  "expiresAt": "2026-10-01T08:10:00.000Z"
}
400Unknown fields, or `expiresInMinutes` / `section` without `email: false`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
409The customer portal is not enabled (Settings → Customer portal) or not in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "portal_disabled",
  "message": "The customer portal is not enabled. Turn it on under Settings > Customer portal."
}
422`not_sent`: inactive customer, portal email template disabled, or the email failed (`url` included when known). `customer_inactive`: sign-in link requested for an inactive customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Email not sent
{
  "error": "not_sent",
  "message": "The customer is inactive and cannot sign in to the portal.",
  "url": "https://app.centrapoint.co.za/portal/acme"
}
Sign-in link for an inactive customer
{
  "error": "customer_inactive",
  "message": "The customer is inactive and cannot sign in to the portal."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/portal-link" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": false,
    "expiresInMinutes": 10,
    "section": "invoices"
  }'

Get a customer's account standing#

GET/api/v1/customers/{id}/standing

The customer's account standing: ok, grace (something is due; show a banner) or locked (the grace period ended; limit the account to billing until it is resolved), why, until when, what is outstanding, and links to add a card (links.addCardUrl) and to pay the oldest outstanding invoice (links.payUrl). Calculated on every request. While the standing rules are off (Settings → Cards & standing) the status is always ok. Rules: a customer on a paid plan without a payment method gets the grace period (default 3 days) from the start of the plan; an invoice past its due date gets it from the due date; customers who existed when the rules were switched on get 14 days first. An open add-card session for the same returnUrl is reused, so polling creates no new ones.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

Query parameters#

Query parameters
FieldTypeDescription
returnUrlstring (uri)

Where the add-card page returns the customer: https, on an origin allowed under Settings → API keys → Allowed return URLs.

paidPlanstring

Overrides the paid-plan check for plans kept outside CentraPoint: true (on a paid plan since the customer was created) or false (free / no plan).

One of: true, false

Responses#

200The customer's standing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: customer_standing

customerIdrequiredstring
statusrequiredstring

grace: show a banner. locked: limit the account to billing (sign in, see and pay invoices, add a card).

One of: ok, grace, locked

reasonrequiredstring | null

What locked the account, or what will lock it first.

One of: no_payment_method, unpaid_invoice, null

reasonsrequiredstring[]

One of: no_payment_method, unpaid_invoice

graceEndsAtrequiredstring (date-time) | null
lockedSincerequiredstring (date-time) | null
lockModerequiredstring

One of: billing_only

rulesEnabledrequiredboolean

The standing rules are switched on (Settings → Cards & standing).

rulesApplyFromrequiredstring (date-time) | null

Customers who existed when the rules were switched on: when the rules start to apply to them.

paidPlanrequiredboolean
hasPaymentMethodrequiredboolean

A usable saved card, an active debit order mandate or a gateway card subscription.

paymentMethodsrequiredobject
Show fields
paymentMethods fields
FieldTypeDescription
cardsrequiredinteger

Usable saved cards.

defaultCardrequiredCard | null
Show fields
defaultCard fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

debitOrderrequiredboolean
gatewaySubscriptionrequiredboolean
outstandingrequiredobject
Show fields
outstanding fields
FieldTypeDescription
amountrequirednumber
overdueAmountrequirednumber
currencyrequiredstring
invoiceIdsrequiredstring[]
invoicesrequiredobject[]
Show fields
invoices fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
dueDaterequiredstring (date-time)
balancerequirednumber
currencyrequiredstring
overduerequiredboolean
paymentPendingrequiredboolean

A card payment for it is with the bank: it does not count until that payment fails.

awaitingCollectionrequiredboolean

Automatic collection is on and the customer has a default saved card, but saved cards cannot be charged yet (no card debit gateway): the invoice waits for you, not for the customer, so it does not count towards a lock. It counts once a charge was attempted and failed.

linksrequiredobject
Show fields
links fields
FieldTypeDescription
addCardUrlrequiredstring | null

Hosted add-card page for the customer.

payUrlrequiredstring | null

Pay page of the oldest outstanding invoice.

checkedAtrequiredstring (date-time)
Example
{
  "object": "customer_standing",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "status": "grace",
  "reason": "unpaid_invoice",
  "reasons": [
    "unpaid_invoice"
  ],
  "graceEndsAt": "2026-10-08T07:00:00.000Z",
  "lockedSince": null,
  "lockMode": "billing_only",
  "rulesEnabled": true,
  "rulesApplyFrom": null,
  "paidPlan": true,
  "hasPaymentMethod": true,
  "paymentMethods": {
    "cards": 1,
    "defaultCard": {
      "object": "card",
      "id": "cmgcard00001visa4242abcd",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "holderName": "T NKOSI",
      "isDefault": true,
      "status": "active",
      "expiring": false,
      "source": "card_setup",
      "createdAt": "2026-10-05T08:00:00.000Z",
      "lastUsedAt": null
    },
    "debitOrder": false,
    "gatewaySubscription": false
  },
  "outstanding": {
    "amount": 299,
    "overdueAmount": 299,
    "currency": "ZAR",
    "invoiceIds": [
      "cmg4i5n6v0001inv0001abcd"
    ],
    "invoices": [
      {
        "id": "cmg4i5n6v0001inv0001abcd",
        "number": "INV-000123",
        "dueDate": "2026-10-05T07:00:00.000Z",
        "balance": 299,
        "currency": "ZAR",
        "overdue": true,
        "paymentPending": false,
        "awaitingCollection": false
      }
    ]
  },
  "links": {
    "addCardUrl": "https://app.centrapoint.co.za/card/Q2x9…",
    "payUrl": "https://app.centrapoint.co.za/pay/k7Rt…"
  },
  "checkedAt": "2026-10-06T09:00:00.000Z"
}
400`paidPlan` is not true or false, or `returnUrl` is not on an allowed origin.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "paidPlan must be true or false"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List a customer's saved cards#

GET/api/v1/customers/{id}/cards

The customer's saved cards, the default first. Never the card number: brand, last four digits and expiry only.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

Query parameters#

Query parameters
FieldTypeDescription
includeRemovedstring

true also returns removed cards.

One of: true, false

Responses#

200The cards.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: list

datarequiredCard[]
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

Example
{
  "object": "list",
  "data": [
    {
      "object": "card",
      "id": "cmgcard00001visa4242abcd",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "holderName": "T NKOSI",
      "isDefault": true,
      "status": "active",
      "expiring": false,
      "source": "card_setup",
      "createdAt": "2026-10-05T08:00:00.000Z",
      "lastUsedAt": null
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Start the hosted add-card page#

POST/api/v1/customers/{id}/cards/setup

Creates a card setup session for the customer and returns its hosted url: redirect the customer there. They pay R1.00 by card to save it; the R1.00 is credited to the customer and taken off their next invoice. Afterwards they return to returnUrl with ?cardSetup=<session id>&status=completed|failed|expired (from the browser: confirm with GET .../cards/setup/{sessionId} or the customer.payment_method.added webhook). Needs a payment gateway that can save cards (Netcash Pay Now).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

Request body fields
FieldTypeDescription
returnUrlstring (uri)

https, on an origin allowed under Settings → API keys → Allowed return URLs.

max 1000 chars

makeDefaultboolean

Make the saved card the customer's default.

default true

expiresInMinutesinteger

≥ 5 · ≤ 10 080 · default 1440

metadataobject

String map echoed on the session.

Responses#

201The session, with its hosted URL.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
objectrequiredstring

One of: card_setup_session

idrequiredstring
customerIdrequiredstring
statusrequiredstring

One of: pending, completed, failed, expired

urlrequiredstring

Hosted add-card page. Redirect the customer here.

returnUrlrequiredstring | null
amountrequirednumber

The verification amount the customer pays (credited to them).

currencyrequiredstring
makeDefaultrequiredboolean
cardIdrequiredstring | null

The saved card once completed.

failureReasonrequiredstring | null

The last attempt of a pending session. no_card_saved: paid, but not by card (the amount is still credited).

One of: declined, cancelled, no_card_saved, null

metadatarequiredobject
expiresAtrequiredstring (date-time)
completedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "object": "card_setup_session",
  "id": "cmgsetup0001session0001ab",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "status": "pending",
  "url": "https://app.centrapoint.co.za/card/Q2x9…",
  "returnUrl": "https://platform.example.co.za/billing",
  "amount": 1,
  "currency": "ZAR",
  "makeDefault": true,
  "cardId": null,
  "failureReason": null,
  "metadata": {
    "platformUserId": "42"
  },
  "expiresAt": "2026-10-06T08:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-10-05T08:00:00.000Z"
}
400Unknown fields, an inactive customer, or a `returnUrl` that is not https or not on an allowed origin.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "returnUrl origin https://evil.example is not allowed - add it under Settings > API keys > Allowed return URLs"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No customer with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer not found"
}
409`card_setup_unavailable`: no payment gateway that can save cards.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "card_setup_unavailable",
  "message": "Saving cards needs a payment gateway that can save cards (Netcash Pay Now). Add one under Settings > Payment gateways."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/setup" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "https://platform.example.co.za/billing",
    "metadata": {
      "platformUserId": "42"
    }
  }'

Get an add-card session#

GET/api/v1/customers/{id}/cards/setup/{sessionId}

pending (open; failureReason describes the last attempt: declined, cancelled or no_card_saved), completed (cardId is the saved card) or expired.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

sessionIdrequiredstring

Card setup session ID.

Responses#

200The session.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: card_setup_session

idrequiredstring
customerIdrequiredstring
statusrequiredstring

One of: pending, completed, failed, expired

urlrequiredstring

Hosted add-card page. Redirect the customer here.

returnUrlrequiredstring | null
amountrequirednumber

The verification amount the customer pays (credited to them).

currencyrequiredstring
makeDefaultrequiredboolean
cardIdrequiredstring | null

The saved card once completed.

failureReasonrequiredstring | null

The last attempt of a pending session. no_card_saved: paid, but not by card (the amount is still credited).

One of: declined, cancelled, no_card_saved, null

metadatarequiredobject
expiresAtrequiredstring (date-time)
completedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "object": "card_setup_session",
  "id": "cmgsetup0001session0001ab",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "status": "completed",
  "url": "https://app.centrapoint.co.za/card/Q2x9…",
  "returnUrl": "https://platform.example.co.za/billing",
  "amount": 1,
  "currency": "ZAR",
  "makeDefault": true,
  "cardId": "cmgcard00001visa4242abcd",
  "failureReason": null,
  "metadata": {
    "platformUserId": "42"
  },
  "expiresAt": "2026-10-06T08:00:00.000Z",
  "completedAt": "2026-10-05T08:03:00.000Z",
  "createdAt": "2026-10-05T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No card setup session with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Card setup session not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/setup/cmgsetup0001session0001ab" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a saved card#

GET/api/v1/customers/{id}/cards/{cardId}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

cardIdrequiredstring

Card ID.

Responses#

200The card.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

Example
{
  "object": "card",
  "id": "cmgcard00001visa4242abcd",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": 12,
  "expiryYear": 2028,
  "holderName": "T NKOSI",
  "isDefault": true,
  "status": "active",
  "expiring": false,
  "source": "card_setup",
  "createdAt": "2026-10-05T08:00:00.000Z",
  "lastUsedAt": null
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No card with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Card not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Remove a saved card#

DELETE/api/v1/customers/{id}/cards/{cardId}

Stops using the card (status removed). A charge of the card not yet sent to the bank is cancelled; when it was the default, the newest other usable card becomes the default. Sends customer.payment_method.removed. Not idempotent: removing it again returns 404.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

cardIdrequiredstring

Card ID.

Responses#

200The removed card.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

Example
{
  "object": "card",
  "id": "cmgcard00001visa4242abcd",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": 12,
  "expiryYear": 2028,
  "holderName": "T NKOSI",
  "isDefault": false,
  "status": "removed",
  "expiring": false,
  "source": "card_setup",
  "createdAt": "2026-10-05T08:00:00.000Z",
  "lastUsedAt": null
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No card with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Card not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X DELETE "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Make a saved card the default#

POST/api/v1/customers/{id}/cards/{cardId}/default

The default card is offered first on the pay page and charged by automatic collection. Expired, failed and removed cards are refused.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

cardIdrequiredstring

Card ID.

Responses#

200The card, now the default.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

Example
{
  "object": "card",
  "id": "cmgcard00001visa4242abcd",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": 12,
  "expiryYear": 2028,
  "holderName": "T NKOSI",
  "isDefault": true,
  "status": "active",
  "expiring": false,
  "source": "card_setup",
  "createdAt": "2026-10-05T08:00:00.000Z",
  "lastUsedAt": null
}
400The card is expired or failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "This card is expired and cannot be the default"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No card with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Card not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd/default" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Charge a saved card#

POST/api/v1/customers/{id}/cards/{cardId}/charges

Charges the customer's saved card without the customer present, for example your platform's own renewal invoice. cardId may be default (the customer's default card). The bank charges the card as a card debit: the charge is created pending and completes (payment.complete) or fails (payment.failed) within about 1-3 business days; both webhooks carry your externalReference and metadata. At most one pending or successful charge per externalReference. The API key needs the cards:charge permission (Settings → API keys). Limits: 60 charges a minute per organisation and 10 a day per customer, besides the key's 120 requests a minute.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Customer ID.

cardIdrequiredstring

Card ID, or default.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountrequirednumber

Amount in ZAR, at most two decimals.

> 0 · ≤ 1 000 000

currencystring

Only ZAR. Default ZAR.

One of: ZAR

descriptionrequiredstring

What the charge is for (dashboard, receipt, your books).

1–255 chars

externalReferencerequiredstring

Your reference, e.g. your invoice number. At most one pending or successful charge per externalReference in your organisation; after a failed charge the same value may be charged again. Sent back in payment webhooks.

1–100 chars

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

Responses#

201The charge, pending until the bank confirms it.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
objectrequiredstring

One of: card_charge

idrequiredstring

Transaction ID.

referencerequiredstring

Payment reference (GET /api/v1/transactions/{reference}, payment webhooks).

statusrequiredstring

pending until the bank confirms (usually 1-3 business days).

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
externalReferencerequiredstring
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerIdrequiredstring
cardrequiredobject
Show fields
card fields
FieldTypeDescription
idstring
brandstring | null
last4string | null
failureReasonrequiredstring | null

Why it failed (e.g. the bank's unpaid reason).

paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "object": "card_charge",
  "id": "cmgchg0001charge0001abcd",
  "reference": "CPA-3F9A1C7B2E4D6F80-1",
  "status": "pending",
  "amount": 199,
  "currency": "ZAR",
  "description": "Pro plan - October 2026",
  "externalReference": "INV-1001",
  "metadata": {
    "platformInvoiceId": "1001"
  },
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "card": {
    "id": "cmgcard00001visa4242abcd",
    "brand": "visa",
    "last4": "4242"
  },
  "failureReason": null,
  "paidAt": null,
  "createdAt": "2026-10-08T06:00:00.000Z"
}
400Invalid body (amount not above zero or with more than two decimals, a currency other than ZAR, unknown fields) or an inactive customer.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403The API key lacks the `cards:charge` permission (`permission_required`), API access is not in your plan (`plan_restricted`), your account is read-only (`account_restricted`) or business verification is not approved (`compliance_required`).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "permission_required",
  "message": "This API key may not charge saved cards. Allow \"Charge saved cards\" for the key under Settings > API keys."
}
404No such customer or card in your organisation (removed cards included).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Customer or card not found"
}
409`charge_exists`: a pending or successful charge with this externalReference exists (returned in `charge`). `no_default_card`: `default` and the customer has no default card. `card_not_chargeable`: the card is expired or failed, or not a Visa / Mastercard your gateway can charge. `card_charges_unavailable`: no gateway that charges saved cards.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "charge_exists",
  "message": "A pending charge with this externalReference already exists",
  "charge": {
    "object": "card_charge",
    "id": "cmgchg0001charge0001abcd",
    "reference": "CPA-3F9A1C7B2E4D6F80-1",
    "status": "pending",
    "amount": 199,
    "currency": "ZAR",
    "description": "Pro plan - October 2026",
    "externalReference": "INV-1001",
    "metadata": {
      "platformInvoiceId": "1001"
    },
    "customerId": "cmg2c0s7t0003cust0001abcd",
    "card": {
      "id": "cmgcard00001visa4242abcd",
      "brand": "visa",
      "last4": "4242"
    },
    "failureReason": null,
    "paidAt": null,
    "createdAt": "2026-10-08T06:00:00.000Z"
  }
}
429Too many charges: 60 a minute per organisation or 10 a day per customer (`Retry-After` says when to try again), or the key's request limit.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "rate_limited",
  "message": "At most 10 saved card charges a day per customer"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/default/charges" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 199,
    "description": "Pro plan - October 2026",
    "externalReference": "INV-1001",
    "metadata": {
      "platformInvoiceId": "1001"
    }
  }'

List invoices#

GET/api/v1/invoices

Newest first, with keyset pagination (limit, startingAfter; the response is { data, hasMore, nextCursor }). status=draft|sent|overdue returns only invoices with nothing paid; use partially_paid for open invoices with part payments. Several statuses can be combined, comma-separated. Each invoice includes its payments.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

One or more comma-separated statuses: draft, sent, overdue, partially_paid, paid, cancelled. draft/sent/overdue exclude invoices that have received money; partially_paid is open invoices with money received. Example: sent,overdue,partially_paid.

numberstring

Exact invoice number, e.g. INV-000042.

customerIdstring

Filter by customer.

customerExternalReferencestring

Filter by the customer's externalReference.

externalReferencestring

The invoice's externalReference (exact match).

fromstring (date)

Start date (YYYY-MM-DD, SAST, inclusive) on the issue date.

tostring (date)

End date (YYYY-MM-DD, SAST, inclusive) on the issue date.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of invoices.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredInvoice[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg2i9n0v0005inv0001abcd",
      "number": "INV-000042",
      "status": "sent",
      "externalReference": "ORDER-1001",
      "customer": {
        "id": "cmg2c0s7t0003cust0001abcd",
        "externalReference": "CRM-1001",
        "email": "[email protected]"
      },
      "currency": "ZAR",
      "issueDate": "2026-09-24T22:00:00.000Z",
      "dueDate": "2026-10-08T21:59:59.000Z",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "lines": [
        {
          "description": "Website hosting - October",
          "details": "Business hosting plan\nDomain: nkosi.example.co.za",
          "quantity": 1,
          "unitPrice": 434.78,
          "taxRate": 15,
          "amount": 434.78,
          "periodStart": null,
          "periodEnd": null
        },
        {
          "description": "Domain renewal (zero-rated)",
          "details": null,
          "quantity": 1,
          "unitPrice": 120,
          "taxRate": 0,
          "amount": 120,
          "periodStart": "2026-10-01",
          "periodEnd": "2027-09-30"
        }
      ],
      "taxInclusive": false,
      "subtotal": 554.78,
      "taxAmount": 65.22,
      "total": 620,
      "amountPaid": 0,
      "amountDue": 620,
      "paidAt": null,
      "payments": [],
      "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
      "notes": "Payment due within 14 days.",
      "metadata": {
        "crmId": "0061x00000AbCdE"
      },
      "createdAt": "2026-09-25T08:05:00.000Z",
      "updatedAt": "2026-09-25T08:05:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status, bad date format or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one or more (comma-separated) of draft, sent, overdue, paid, cancelled, partially_paid"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create an invoice#

POST/api/v1/invoices

Creates an invoice with per-line VAT (201). If externalReference matches an existing invoice, that invoice is returned unchanged with 200 (the body is not applied and it is not re-sent). A pay link for the balance is created when your plan includes payment links and a gateway accepts the currency. Invoices are drafts by default. status: "sent" (or issue: true) creates the invoice issued without an email; send: true issues it and emails it. invoice.sent is sent either way. Requires the Invoicing feature.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring

The customer's CentraPoint ID. Send exactly one of customerId or customer.

customerobject | object

The customer, by CentraPoint ID or by your externalReference. Send exactly one of customerId or customer.

Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencestring

Your ID for the invoice. If an invoice with this reference exists, it is returned unchanged with 200.

1–190 chars

currencystring

ISO 4217 code (validated). No gateway is required: invoices can be paid offline, but payUrl is only created when a gateway accepts the currency.

default "ZAR"

issueDatestring (date)

YYYY-MM-DD (South African time). Default today.

dueDatestring (date)

YYYY-MM-DD (South African time, end of day). Default: today plus your invoice due days setting.

periodStartstring (date)

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Omit for once-off sales.

periodEndstring (date)

Last day of the billing period (YYYY-MM-DD, inclusive).

linesrequiredobject[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring

1–1000 chars

detailsstring | null

Detailed, multi-line description shown under description on PDFs, emails and the portal (plan features, usage, domain, reference...).

max 4000 chars

quantityrequirednumber

> 0 · ≤ 1 000 000

unitPricerequirednumber

Excluding VAT.

≥ 0 · ≤ 100 000 000

taxRatenumber

VAT %. Defaults to your organisation's VAT rate.

≥ 0 · ≤ 100

periodStartstring (date)

The line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, e.g. a prorated add-on. Send both or neither; periodEnd must be on or after periodStart.

periodEndstring (date)

Last day of the line's own period (YYYY-MM-DD, inclusive).

notesstring

Defaults to your invoice terms.

max 4000 chars

taxInclusiveboolean

Line prices already include tax. Default false: tax is added on top of the line prices. A line's own taxRate still wins; lines without one use your organisation's tax settings (Settings → Tax).

default false

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sendboolean

Default false. true issues the invoice (sent) and emails it to the customer with the pay link. With send: false, status: "sent" or issue: true issues it without an email.

default false

statusstring

sent issues the invoice without emailing it (unless send is true), like POST /api/v1/invoices/{id}/issue; invoice.sent is sent. draft cannot be combined with send: true or issue: true (400).

One of: draft, sent

default "draft"

issueboolean

Same as status: "sent": issue without emailing.

Responses#

200An invoice with this externalReference already existed; returned unchanged.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
201Invoice created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
400Validation failed, invalid ISO 4217 currency, customer not found, or totals invalid.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Customer not found"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalReference": "CRM-1001"
    },
    "externalReference": "ORDER-1001",
    "dueDate": "2026-10-08",
    "periodStart": "2026-10-01",
    "periodEnd": "2026-10-31",
    "lines": [
      {
        "description": "Website hosting - October",
        "details": "Business hosting plan\nDomain: nkosi.example.co.za",
        "quantity": 1,
        "unitPrice": 434.78
      },
      {
        "description": "Domain renewal (zero-rated)",
        "quantity": 1,
        "unitPrice": 120,
        "taxRate": 0,
        "periodStart": "2026-10-01",
        "periodEnd": "2027-09-30"
      }
    ],
    "metadata": {
      "crmId": "0061x00000AbCdE"
    },
    "send": true
  }'

Get an invoice#

GET/api/v1/invoices/{id}

By ID or invoice number. Includes payments: offline payments and completed transactions linked to the invoice.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Responses#

200The invoice.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID or number in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Send an invoice#

POST/api/v1/invoices/{id}/send

Emails the invoice to the customer, with a pay link for the balance when possible. A draft becomes sent. Paid or cancelled invoices cannot be sent. No body is required. Always emails; to issue without an email use POST /api/v1/invoices/{id}/issue.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

object

Responses#

200The invoice after sending.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
400The invoice is in a state that does not allow this, or validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invoice is paid"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/send" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Issue an invoice without emailing#

POST/api/v1/invoices/{id}/issue

Marks a draft invoice as issued (sent) without emailing the customer: it becomes payable, reminders and the overdue job apply, it syncs to accounting, invoice.sent is sent and a pay link is created when possible. Already issued invoices (sent, overdue, partially paid, paid) are returned unchanged; cancelled invoices return 400. No body is required.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

object

Responses#

200The issued invoice (or the unchanged invoice when it was already issued).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
400The invoice is cancelled.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invoice is cancelled"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/issue" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Cancel an invoice#

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

Voids an unpaid (or partially paid) invoice and deactivates its pay links. Cancelling an already cancelled invoice returns it unchanged. Paid invoices cannot be cancelled.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

Request body fields
FieldTypeDescription
reasonstring

Appended to the invoice notes.

max 500 chars

Responses#

200The cancelled invoice.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "cancelled",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 0,
  "amountDue": 620,
  "paidAt": null,
  "payments": [],
  "payUrl": null,
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
400The invoice is in a state that does not allow this, or validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Paid invoices cannot be cancelled - record a refund or credit instead"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Order cancelled by customer"
  }'

Record an offline payment or allocate an existing payment#

POST/api/v1/invoices/{id}/payments

Two bodies. { amount, method, reference?, paidAt? } records money received outside CentraPoint's gateways (EFT, cash, card machine, wallet credit…). { transactionReference } allocates an existing completed CentraPoint payment that is not linked to an invoice yet (no new money): 201, or 200 when it is already allocated to this invoice; 409 already_allocated when it belongs to another invoice; 400 when it is not complete or was refunded, is in another currency or of another customer, or would overpay. The invoice becomes paid when fully paid (pay links are deactivated) or partially_paid otherwise. Always send an Idempotency-Key so a retry does not record an offline payment twice.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

InvoicePaymentCreate | InvoicePaymentAllocate

Responses#

200Allocation only: the payment was already allocated to this invoice; the invoice, unchanged.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "paid",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 620,
  "amountDue": 0,
  "paidAt": "2026-10-02T08:15:00.000Z",
  "payments": [
    {
      "id": "cmg2q8r4s0009ipay0001abcd",
      "source": "offline",
      "origin": "api",
      "method": "eft",
      "status": "complete",
      "amount": 620,
      "refundedAmount": 0,
      "currency": "ZAR",
      "date": "2026-10-02T08:15:00.000Z",
      "reference": "FNB 2026-10-02 NKOSI",
      "transactionReference": null
    }
  ],
  "payUrl": null,
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
201Payment recorded or allocated; the updated invoice.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000042",
  "status": "paid",
  "externalReference": "ORDER-1001",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "currency": "ZAR",
  "issueDate": "2026-09-24T22:00:00.000Z",
  "dueDate": "2026-10-08T21:59:59.000Z",
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "lines": [
    {
      "description": "Website hosting - October",
      "details": "Business hosting plan\nDomain: nkosi.example.co.za",
      "quantity": 1,
      "unitPrice": 434.78,
      "taxRate": 15,
      "amount": 434.78,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Domain renewal (zero-rated)",
      "details": null,
      "quantity": 1,
      "unitPrice": 120,
      "taxRate": 0,
      "amount": 120,
      "periodStart": "2026-10-01",
      "periodEnd": "2027-09-30"
    }
  ],
  "taxInclusive": false,
  "subtotal": 554.78,
  "taxAmount": 65.22,
  "total": 620,
  "amountPaid": 620,
  "amountDue": 0,
  "paidAt": "2026-10-02T08:15:00.000Z",
  "payments": [
    {
      "id": "cmg2q8r4s0009ipay0001abcd",
      "source": "offline",
      "origin": "api",
      "method": "eft",
      "status": "complete",
      "amount": 620,
      "refundedAmount": 0,
      "currency": "ZAR",
      "date": "2026-10-02T08:15:00.000Z",
      "reference": "FNB 2026-10-02 NKOSI",
      "transactionReference": null
    }
  ],
  "payUrl": null,
  "notes": "Payment due within 14 days.",
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:05:00.000Z",
  "updatedAt": "2026-09-25T08:05:00.000Z"
}
400The invoice is in a state that does not allow this, or validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Amount exceeds the outstanding balance of 620.00"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
409`already_allocated`: the transaction is allocated to another invoice; or `idempotency_conflict`: the Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
already_allocated
{
  "error": "already_allocated",
  "message": "Transaction CP-20260930-7K2M9QXA is already allocated to another invoice"
}
idempotency_conflict
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/payments" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionReference": "CP-20260930-7K2M9QXA"
  }'

Download an invoice PDF#

GET/api/v1/invoices/{id}/pdf

The branded invoice PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Invoice ID or invoice number (e.g. INV-000042).

Responses#

200The PDF.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Content-Disposition – `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No invoice with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Invoice not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List quotes#

GET/api/v1/quotes

Newest first, with keyset pagination. Sent quotes past their expiry date are reported as expired.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

One of: draft, sent, accepted, declined, expired, invoiced

customerIdstring
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of quotes.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredQuote[]
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "object": "quote",
      "id": "cmg3q1a2b0001quo0001abcd",
      "number": "QUO-000017",
      "status": "sent",
      "issueDate": "2026-09-26T22:00:00.000Z",
      "expiryDate": "2026-10-26T21:59:59.000Z",
      "periodStart": null,
      "periodEnd": null,
      "currency": "ZAR",
      "taxInclusive": false,
      "subtotal": 5000,
      "taxAmount": 750,
      "total": 5750,
      "notes": "Valid for 30 days.",
      "customer": {
        "id": "cmg2c0s7t0003cust0001abcd",
        "externalReference": "CRM-1001",
        "email": "[email protected]"
      },
      "invoice": null,
      "lineItems": [
        {
          "description": "Website redesign",
          "details": "5 pages, mobile layout\nTwo rounds of changes",
          "quantity": 1,
          "unitPrice": 4500,
          "amount": 4500,
          "taxRate": 15,
          "periodStart": null,
          "periodEnd": null
        },
        {
          "description": "Hosting setup",
          "details": null,
          "quantity": 1,
          "unitPrice": 500,
          "amount": 500,
          "taxRate": 15,
          "periodStart": null,
          "periodEnd": null
        }
      ],
      "sentAt": "2026-09-27T08:00:00.000Z",
      "acceptedAt": null,
      "declinedAt": null,
      "createdAt": "2026-09-27T07:55:00.000Z",
      "updatedAt": "2026-09-27T08:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of draft, sent, accepted, declined, expired, invoiced"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a quote#

POST/api/v1/quotes

Creates a quote with per-line VAT (same rules as invoices). send: true creates it as sent. Emits quote.created (and quote.sent). Requires the Invoicing feature.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring

Send exactly one of customerId or customerExternalReference (create); at most one (update).

customerExternalReferencestring

Your reference of an existing customer.

max 190 chars

lineItemsrequiredFinanceLineInput[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring

1–1000 chars

detailsstring | null

Detailed, multi-line description shown under description on PDFs, emails and the portal (plan features, usage, domain, reference...).

max 4000 chars

quantityrequirednumber

> 0 · ≤ 1 000 000

unitPricerequirednumber

≥ 0 · ≤ 100 000 000

taxRatenumber

Default: your organisation's tax rate (Settings → Tax); for a credit note against an invoice, the invoice's rate.

≥ 0 · ≤ 100

periodStartstring (date)

The line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, e.g. a prorated add-on. Send both or neither; periodEnd must be on or after periodStart.

periodEndstring (date)

Last day of the line's own period (YYYY-MM-DD, inclusive).

currencystring

ISO 4217, default ZAR.

issueDatestring (date)

YYYY-MM-DD, default today.

expiryDatestring (date)

YYYY-MM-DD, last valid day (inclusive). Default: no expiry.

periodStartstring (date)

First day of the billing period the quote covers (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Copied to the invoice when the quote is converted.

periodEndstring (date)

Last day of the billing period (YYYY-MM-DD, inclusive).

notesstring

max 4000 chars

taxInclusiveboolean

default false

sendboolean

Create it as sent.

default false

Responses#

201Quote created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "sent",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": null,
  "declinedAt": null,
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
400Validation failed, customer not found, invalid currency, expiry before issue date, or totals invalid.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Customer not found"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/quotes" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalReference": "CRM-1001",
    "expiryDate": "2026-10-26",
    "lineItems": [
      {
        "description": "Website redesign",
        "quantity": 1,
        "unitPrice": 4500
      },
      {
        "description": "Hosting setup",
        "quantity": 1,
        "unitPrice": 500
      }
    ],
    "notes": "Valid for 30 days.",
    "send": true
  }'

Get a quote#

GET/api/v1/quotes/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Responses#

200The quote.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "sent",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": null,
  "declinedAt": null,
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a quote#

PATCH/api/v1/quotes/{id}

Edits a draft or sent quote. Omitted fields keep their value; null clears expiryDate, notes or the billing period; lineItems replaces every line. Emits quote.updated.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring

Send exactly one of customerId or customerExternalReference (create); at most one (update).

customerExternalReferencestring

Your reference of an existing customer.

max 190 chars

lineItemsFinanceLineInput[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring

1–1000 chars

detailsstring | null

Detailed, multi-line description shown under description on PDFs, emails and the portal (plan features, usage, domain, reference...).

max 4000 chars

quantityrequirednumber

> 0 · ≤ 1 000 000

unitPricerequirednumber

≥ 0 · ≤ 100 000 000

taxRatenumber

Default: your organisation's tax rate (Settings → Tax); for a credit note against an invoice, the invoice's rate.

≥ 0 · ≤ 100

periodStartstring (date)

The line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, e.g. a prorated add-on. Send both or neither; periodEnd must be on or after periodStart.

periodEndstring (date)

Last day of the line's own period (YYYY-MM-DD, inclusive).

currencystring

ISO 4217, default ZAR.

issueDatestring (date)

YYYY-MM-DD, default today.

expiryDatestring (date) | null
periodStartstring (date) | null

YYYY-MM-DD, inclusive. null clears the period (clear both dates together); omitted keeps it. Send both or neither when setting; periodEnd must be on or after periodStart.

periodEndstring (date) | null

YYYY-MM-DD, inclusive. null clears it; omitted keeps it.

notesstring | null

max 4000 chars

taxInclusiveboolean

default false

Responses#

200The updated quote.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "sent",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": null,
  "declinedAt": null,
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
400Validation failed, or the quote is not draft or sent.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A accepted quote cannot be edited"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "expiryDate": "2026-11-15",
    "notes": "Valid until 15 November."
  }'

Delete a draft quote#

DELETE/api/v1/quotes/{id}

Permanently deletes a draft quote. Other quotes return 400 (decline them instead). No webhook is sent.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Responses#

200Deleted.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring
deletedrequiredboolean

One of: true

Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "deleted": true
}
400The quote is not a draft.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Only draft quotes can be deleted - decline it instead"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X DELETE "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Mark a quote sent#

POST/api/v1/quotes/{id}/send

Marks a draft or expired quote sent (an already sent quote is returned unchanged). CentraPoint does not email quotes; share the PDF. Emits quote.sent.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The updated quote.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "sent",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": null,
  "declinedAt": null,
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
400The status change is not allowed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A invoiced quote cannot be marked sent"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/send" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Mark a quote accepted#

POST/api/v1/quotes/{id}/accept

Marks a draft, sent or expired quote accepted. Emits quote.accepted.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The updated quote.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "accepted",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": "2026-09-29T11:02:09.000Z",
  "declinedAt": null,
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
400The status change is not allowed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A invoiced quote cannot be marked accepted"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/accept" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Mark a quote declined#

POST/api/v1/quotes/{id}/decline

Marks a draft, sent, expired or accepted quote declined. Emits quote.declined.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The updated quote.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "quote",
  "id": "cmg3q1a2b0001quo0001abcd",
  "number": "QUO-000017",
  "status": "declined",
  "issueDate": "2026-09-26T22:00:00.000Z",
  "expiryDate": "2026-10-26T21:59:59.000Z",
  "periodStart": null,
  "periodEnd": null,
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 5000,
  "taxAmount": 750,
  "total": 5750,
  "notes": "Valid for 30 days.",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": null,
  "lineItems": [
    {
      "description": "Website redesign",
      "details": "5 pages, mobile layout\nTwo rounds of changes",
      "quantity": 1,
      "unitPrice": 4500,
      "amount": 4500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    },
    {
      "description": "Hosting setup",
      "details": null,
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "taxRate": 15,
      "periodStart": null,
      "periodEnd": null
    }
  ],
  "sentAt": "2026-09-27T08:00:00.000Z",
  "acceptedAt": null,
  "declinedAt": "2026-09-29T11:02:09.000Z",
  "createdAt": "2026-09-27T07:55:00.000Z",
  "updatedAt": "2026-09-27T08:00:00.000Z"
}
400The status change is not allowed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A invoiced quote cannot be marked declined"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/decline" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Convert a quote to an invoice#

POST/api/v1/quotes/{id}/convert

Creates a draft invoice from the quote's lines (due in dueDays), marks the quote invoiced and links them. A pay link is created when your plan includes payment links and a gateway accepts the currency. Emits quote.invoiced and invoice.created.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

Request body fields
FieldTypeDescription
dueDaysinteger

Default: your invoice due-days setting.

≥ 0 · ≤ 365

Responses#

201The invoiced quote and the new invoice.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
quoterequiredQuote

Returned by every quote endpoint and sent as data in quote.* webhooks.

Show fields
quote fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
invoicerequiredInvoice
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "quote": {
    "object": "quote",
    "id": "cmg3q1a2b0001quo0001abcd",
    "number": "QUO-000017",
    "status": "invoiced",
    "issueDate": "2026-09-26T22:00:00.000Z",
    "expiryDate": "2026-10-26T21:59:59.000Z",
    "periodStart": null,
    "periodEnd": null,
    "currency": "ZAR",
    "taxInclusive": false,
    "subtotal": 5000,
    "taxAmount": 750,
    "total": 5750,
    "notes": "Valid for 30 days.",
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "invoice": {
      "id": "cmg3i2j3k0004inv0061abcd",
      "number": "INV-000061",
      "status": "draft",
      "externalReference": null
    },
    "lineItems": [
      {
        "description": "Website redesign",
        "details": "5 pages, mobile layout\nTwo rounds of changes",
        "quantity": 1,
        "unitPrice": 4500,
        "amount": 4500,
        "taxRate": 15,
        "periodStart": null,
        "periodEnd": null
      },
      {
        "description": "Hosting setup",
        "details": null,
        "quantity": 1,
        "unitPrice": 500,
        "amount": 500,
        "taxRate": 15,
        "periodStart": null,
        "periodEnd": null
      }
    ],
    "sentAt": "2026-09-27T08:00:00.000Z",
    "acceptedAt": "2026-09-29T11:05:00.000Z",
    "declinedAt": null,
    "createdAt": "2026-09-27T07:55:00.000Z",
    "updatedAt": "2026-09-27T08:00:00.000Z"
  },
  "invoice": {
    "id": "cmg3i2j3k0004inv0061abcd",
    "number": "INV-000061",
    "status": "draft",
    "externalReference": null,
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "currency": "ZAR",
    "issueDate": "2026-09-24T22:00:00.000Z",
    "dueDate": "2026-10-08T21:59:59.000Z",
    "periodStart": "2026-10-01",
    "periodEnd": "2026-10-31",
    "lines": [
      {
        "description": "Website hosting - October",
        "details": "Business hosting plan\nDomain: nkosi.example.co.za",
        "quantity": 1,
        "unitPrice": 434.78,
        "taxRate": 15,
        "amount": 434.78,
        "periodStart": null,
        "periodEnd": null
      },
      {
        "description": "Domain renewal (zero-rated)",
        "details": null,
        "quantity": 1,
        "unitPrice": 120,
        "taxRate": 0,
        "amount": 120,
        "periodStart": "2026-10-01",
        "periodEnd": "2027-09-30"
      }
    ],
    "taxInclusive": false,
    "subtotal": 554.78,
    "taxAmount": 65.22,
    "total": 620,
    "amountPaid": 0,
    "amountDue": 620,
    "paidAt": null,
    "payments": [],
    "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
    "notes": "Payment due within 14 days.",
    "metadata": {
      "crmId": "0061x00000AbCdE"
    },
    "createdAt": "2026-09-25T08:05:00.000Z",
    "updatedAt": "2026-09-25T08:05:00.000Z"
  }
}
400The quote is declined or already invoiced.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "This quote has already been invoiced"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/convert" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDays": 14
  }'

Download a quote PDF#

GET/api/v1/quotes/{id}/pdf

The branded quote PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Quote ID or quote number.

Responses#

200The PDF.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Content-Disposition – `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No quote with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Quote not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List credit notes#

GET/api/v1/credit-notes

Newest first, with keyset pagination.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

One of: draft, issued, applied, refunded, void

customerIdstring
invoiceIdstring
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of credit notes.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredCreditNote[]
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "object": "credit_note",
      "id": "cmg3c7d8e0002crn0001abcd",
      "number": "CN-000008",
      "status": "issued",
      "issueDate": "2026-09-27T09:10:00.000Z",
      "periodStart": "2026-09-01",
      "periodEnd": "2026-09-30",
      "reason": "Hosting downtime 12-14 September",
      "currency": "ZAR",
      "taxInclusive": false,
      "subtotal": 200,
      "taxAmount": 30,
      "total": 230,
      "amountApplied": 100,
      "amountRefunded": 0,
      "balance": 130,
      "customer": {
        "id": "cmg2c0s7t0003cust0001abcd",
        "externalReference": "CRM-1001",
        "email": "[email protected]"
      },
      "invoice": {
        "id": "cmg2i9n0v0005inv0001abcd",
        "number": "INV-000042",
        "externalReference": "ORDER-1001"
      },
      "lineItems": [
        {
          "description": "Service credit - downtime",
          "details": "Outage 12-14 September (3 days)",
          "quantity": 1,
          "unitPrice": 200,
          "amount": 200,
          "taxRate": 15,
          "periodStart": "2026-09-12",
          "periodEnd": "2026-09-14"
        }
      ],
      "history": [
        {
          "at": "2026-09-27T09:20:00.000Z",
          "kind": "applied",
          "amount": 100,
          "ref": "INV-000051"
        }
      ],
      "refunds": [],
      "payouts": [],
      "issuedAt": "2026-09-27T09:10:00.000Z",
      "voidedAt": null,
      "createdAt": "2026-09-27T09:10:00.000Z",
      "updatedAt": "2026-09-27T09:20:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of draft, issued, applied, refunded, void"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a credit note#

POST/api/v1/credit-notes

Creates a credit note, optionally against an invoice (customer, currency and tax rate then come from the invoice; credit notes on one invoice can't exceed its total). issue: true issues it immediately. Emits credit_note.created (and credit_note.issued). Requires the Invoicing feature.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring
customerExternalReferencestring

max 190 chars

invoiceIdstring

Credit against this invoice: its customer, currency and tax rate are used.

lineItemsrequiredFinanceLineInput[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring

1–1000 chars

detailsstring | null

Detailed, multi-line description shown under description on PDFs, emails and the portal (plan features, usage, domain, reference...).

max 4000 chars

quantityrequirednumber

> 0 · ≤ 1 000 000

unitPricerequirednumber

≥ 0 · ≤ 100 000 000

taxRatenumber

Default: your organisation's tax rate (Settings → Tax); for a credit note against an invoice, the invoice's rate.

≥ 0 · ≤ 100

periodStartstring (date)

The line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, e.g. a prorated add-on. Send both or neither; periodEnd must be on or after periodStart.

periodEndstring (date)

Last day of the line's own period (YYYY-MM-DD, inclusive).

currencystring

ISO 4217, default ZAR (the invoice's when invoiceId is sent).

taxInclusiveboolean

default false

periodStartstring (date)

First day of the period being credited (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Default: the invoice's period when invoiceId is sent.

periodEndstring (date)

Last day of the billing period (YYYY-MM-DD, inclusive).

reasonstring

max 1000 chars

notesstring

max 4000 chars

issueboolean

Issue it immediately.

default false

Responses#

201Credit note created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "issued",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 0,
  "amountRefunded": 0,
  "balance": 230,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": null,
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:10:00.000Z"
}
400Validation failed; customer or invoice not found; the invoice belongs to another customer; credit above the invoice total.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Credit notes cannot exceed the invoice total of 620.00"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "cmg2i9n0v0005inv0001abcd",
    "reason": "Hosting downtime 12-14 September",
    "lineItems": [
      {
        "description": "Service credit - downtime",
        "quantity": 1,
        "unitPrice": 200
      }
    ],
    "issue": true
  }'

Get a credit note#

GET/api/v1/credit-notes/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Responses#

200The credit note.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "issued",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 100,
  "amountRefunded": 0,
  "balance": 130,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [
    {
      "at": "2026-09-27T09:20:00.000Z",
      "kind": "applied",
      "amount": 100,
      "ref": "INV-000051"
    }
  ],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": null,
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:20:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Issue a credit note#

POST/api/v1/credit-notes/{id}/issue

Draft → issued, so its credit can be used. Emits credit_note.issued.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The issued credit note.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "issued",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 100,
  "amountRefunded": 0,
  "balance": 130,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [
    {
      "at": "2026-09-27T09:20:00.000Z",
      "kind": "applied",
      "amount": 100,
      "ref": "INV-000051"
    }
  ],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": null,
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:20:00.000Z"
}
400Not a draft.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Only draft credit notes can be issued"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/issue" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Void a credit note#

POST/api/v1/credit-notes/{id}/void

Voids an unused draft or issued credit note (a void one is returned unchanged). The reason is added to the notes. Emits credit_note.voided.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

Request body fields
FieldTypeDescription
reasonstring

max 500 chars

Responses#

200The void credit note.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "void",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 0,
  "amountRefunded": 0,
  "balance": 230,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": "2026-09-27T09:30:00.000Z",
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:20:00.000Z"
}
400The credit note has been used.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "This credit note has been used - it cannot be voided"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/void" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Issued in error"
  }'

Apply credit to an invoice#

POST/api/v1/credit-notes/{id}/apply

Records an invoice payment (method credit_note) on an unpaid invoice of the same customer and currency. Emits credit_note.applied (and invoice.paid / invoice.partially_paid). Always send an Idempotency-Key.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
invoiceIdrequiredstring

Unpaid invoice of the same customer and currency.

amountrequirednumber

> 0

Responses#

200The updated credit note.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "issued",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 100,
  "amountRefunded": 0,
  "balance": 130,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [
    {
      "at": "2026-09-27T09:20:00.000Z",
      "kind": "applied",
      "amount": 100,
      "ref": "INV-000051"
    }
  ],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": null,
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:20:00.000Z"
}
400Not issued, amount above the balance, or invoice not found / another customer / another currency.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "The credit balance is 130.00"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/apply" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "cmg2i9n0v0005inv0051abcd",
    "amount": 100
  }'

Pay credit back#

POST/api/v1/credit-notes/{id}/refund

Pays credit back: payment records a refund on one of the customer's completed payments (process it in the gateway's portal); payout schedules a Netcash payout to the customer's bank account (ZAR); manual records a pay-back done outside CentraPoint. Emits credit_note.refunded. Always send an Idempotency-Key.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

object | object | object

Responses#

200The updated credit note.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "credit_note",
  "id": "cmg3c7d8e0002crn0001abcd",
  "number": "CN-000008",
  "status": "applied",
  "issueDate": "2026-09-27T09:10:00.000Z",
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "reason": "Hosting downtime 12-14 September",
  "currency": "ZAR",
  "taxInclusive": false,
  "subtotal": 200,
  "taxAmount": 30,
  "total": 230,
  "amountApplied": 100,
  "amountRefunded": 130,
  "balance": 0,
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "invoice": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "externalReference": "ORDER-1001"
  },
  "lineItems": [
    {
      "description": "Service credit - downtime",
      "details": "Outage 12-14 September (3 days)",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200,
      "taxRate": 15,
      "periodStart": "2026-09-12",
      "periodEnd": "2026-09-14"
    }
  ],
  "history": [
    {
      "at": "2026-09-27T09:20:00.000Z",
      "kind": "applied",
      "amount": 100,
      "ref": "INV-000051"
    },
    {
      "at": "2026-09-30T10:00:00.000Z",
      "kind": "manual",
      "amount": 130,
      "ref": "FNB 2026-09-30 NKOSI",
      "note": "eft"
    }
  ],
  "refunds": [],
  "payouts": [],
  "issuedAt": "2026-09-27T09:10:00.000Z",
  "voidedAt": null,
  "createdAt": "2026-09-27T09:10:00.000Z",
  "updatedAt": "2026-09-27T09:20:00.000Z"
}
400Not issued; amount above the balance; payment not found or not refundable; invalid bank details; no payout gateway; non-ZAR payout; action date in the past.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Payment not found"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or invoicing, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/refund" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "payout",
    "amount": 130,
    "actionDate": "2026-10-01",
    "bank": {
      "accountHolder": "T Nkosi",
      "accountNumber": "62000000000",
      "branchCode": "250655",
      "accountType": "current",
      "bankName": "FNB"
    },
    "beneficiaryEmail": "[email protected]"
  }'

Download a credit note PDF#

GET/api/v1/credit-notes/{id}/pdf

The branded credit note PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Credit note ID or number.

Responses#

200The PDF.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Content-Disposition – `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No credit note with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Credit note not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/pdf" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List subscriptions#

GET/api/v1/subscriptions

Gateway-managed subscriptions started by recurring payment links, newest first.

Query parameters#

Query parameters
FieldTypeDescription
externalReferencestring

The payment link's externalReference.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Subscriptions.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredSubscription[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

Example
{
  "data": [
    {
      "id": "cmg2s5b8k0007sub0001abcd",
      "status": "active",
      "frequency": "monthly",
      "amount": 499,
      "currency": "ZAR",
      "gateway": "payfast",
      "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
      "externalReference": "SUB-ACME-PRO",
      "metadata": {
        "plan": "pro"
      },
      "createdAt": "2026-09-25T08:14:04.000Z",
      "updatedAt": "2026-09-25T08:14:04.000Z"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access (or the feature) is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Get a subscription#

GET/api/v1/subscriptions/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The subscription.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

Example
{
  "id": "cmg2s5b8k0007sub0001abcd",
  "status": "active",
  "frequency": "monthly",
  "amount": 499,
  "currency": "ZAR",
  "gateway": "payfast",
  "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
  "externalReference": "SUB-ACME-PRO",
  "metadata": {
    "plan": "pro"
  },
  "createdAt": "2026-09-25T08:14:04.000Z",
  "updatedAt": "2026-09-25T08:14:04.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access (or the feature) is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Pause a subscription#

POST/api/v1/subscriptions/{id}/pause

Pauses future collections at the gateway and sends subscription.paused. Allowed from active. Supported on gateways that can pause subscriptions (capabilities.pause), e.g. PayFast, Netcash Pay Now. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The subscription (status `paused`).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

Example
{
  "id": "cmg2s5b8k0007sub0001abcd",
  "status": "paused",
  "frequency": "monthly",
  "amount": 499,
  "currency": "ZAR",
  "gateway": "payfast",
  "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
  "externalReference": "SUB-ACME-PRO",
  "metadata": {
    "plan": "pro"
  },
  "createdAt": "2026-09-25T08:14:04.000Z",
  "updatedAt": "2026-09-25T08:14:04.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`invalid_state`: not allowed from the current status. `unsupported`: the subscription's gateway can't do this, e.g. Netcash Pay Now subscriptions can only be cancelled.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
invalidState
{
  "error": "invalid_state",
  "message": "Subscription is cancelled"
}
unsupported
{
  "error": "unsupported",
  "message": "Netcash Pay Now does not support pausing subscriptions"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
502The gateway rejected or failed the request. Nothing changed; retry later.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "gateway_error",
  "message": "The payment gateway did not accept the request (pausing). Please try again."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/pause" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Resume a subscription#

POST/api/v1/subscriptions/{id}/resume

Resumes a paused subscription at the gateway and sends subscription.resumed. Allowed from paused. Supported on gateways that can pause subscriptions (capabilities.resume), e.g. PayFast, Netcash Pay Now. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The subscription (status `active`).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

Example
{
  "id": "cmg2s5b8k0007sub0001abcd",
  "status": "active",
  "frequency": "monthly",
  "amount": 499,
  "currency": "ZAR",
  "gateway": "payfast",
  "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
  "externalReference": "SUB-ACME-PRO",
  "metadata": {
    "plan": "pro"
  },
  "createdAt": "2026-09-25T08:14:04.000Z",
  "updatedAt": "2026-09-25T08:14:04.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`invalid_state`: not allowed from the current status. `unsupported`: the subscription's gateway can't do this, e.g. Netcash Pay Now subscriptions can only be cancelled.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
invalidState
{
  "error": "invalid_state",
  "message": "Subscription is cancelled"
}
unsupported
{
  "error": "unsupported",
  "message": "Netcash Pay Now does not support resuming subscriptions"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
502The gateway rejected or failed the request. Nothing changed; retry later.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "gateway_error",
  "message": "The payment gateway did not accept the request (resuming). Please try again."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/resume" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Cancel a subscription#

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

Stops future collections at the gateway and sends subscription.cancelled. Allowed from active or paused. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The cancelled subscription.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

Example
{
  "id": "cmg2s5b8k0007sub0001abcd",
  "status": "cancelled",
  "frequency": "monthly",
  "amount": 499,
  "currency": "ZAR",
  "gateway": "payfast",
  "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
  "externalReference": "SUB-ACME-PRO",
  "metadata": {
    "plan": "pro"
  },
  "createdAt": "2026-09-25T08:14:04.000Z",
  "updatedAt": "2026-09-25T08:14:04.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`invalid_state`: not allowed from the current status. `unsupported`: the gateway can't cancel through CentraPoint.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_state",
  "message": "Subscription is cancelled"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
502The gateway rejected or failed the request. Nothing changed; retry later.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "gateway_error",
  "message": "The payment gateway did not accept the cancellation. Please try again."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List packages#

GET/api/v1/packages

Subscription packages with their plans, in sort order. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Query parameters#

Query parameters
FieldTypeDescription
enabledstring

true: only enabled packages, each with only its enabled plans. false: only disabled packages.

One of: true, false

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Packages.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredPackage[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: package

namerequiredstring
descriptionrequiredstring | null
enabledrequiredboolean
sortOrderrequiredinteger
defaultProviderIdrequiredstring | null

Gateway used for gateway subscriptions when none is given.

plansPlan[]

Sorted by sortOrder, then price.

Show fields
plans fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg4p1a2b0001pkg0001abcd",
      "object": "package",
      "name": "Acme Cloud",
      "description": "Hosted project management",
      "enabled": true,
      "sortOrder": 0,
      "defaultProviderId": "cmg1p0v1d0001prov0001abcd",
      "plans": [
        {
          "id": "cmg4p1a2b0002pln0001abcd",
          "object": "plan",
          "packageId": "cmg4p1a2b0001pkg0001abcd",
          "name": "Pro",
          "description": "For growing teams",
          "features": [
            "Unlimited projects",
            "Priority support"
          ],
          "hasCallToAction": false,
          "callToActionUrl": null,
          "hasContactUs": false,
          "enabled": true,
          "frequency": "monthly",
          "amount": 499,
          "setupFee": 0,
          "currency": "ZAR",
          "trialDays": 14,
          "billingCycles": null,
          "providerIds": [],
          "sortOrder": 1,
          "createdAt": "2026-09-28T08:00:00.000Z",
          "updatedAt": "2026-09-28T08:00:00.000Z"
        }
      ],
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a package#

POST/api/v1/packages

Creates a package, optionally with up to 20 plans. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
namerequiredstring

1–120 chars

descriptionstring | null

max 2000 chars

enabledboolean

default true

sortOrderinteger

≥ -10000 · ≤ 10 000

defaultProviderIdstring | null

One of your payment providers.

plansPlanCreate[]

Plans to create with the package.

Show fields
plans fields
FieldTypeDescription
namerequiredstring

1–120 chars

codestring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

descriptionstring | null

max 2000 chars

featuresstring[]
hasCallToActionboolean

Requires callToActionUrl.

callToActionUrlstring | null

http(s) URL.

max 1000 chars

hasContactUsboolean
enabledboolean

default true

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

0 is allowed: free plans activate without a payment.

≥ 0 · ≤ 100 000 000

setupFeenumber

≥ 0 · ≤ 100 000 000

currencystring

ISO 4217 code; default ZAR.

trialDaysinteger

≥ 0 · ≤ 730

billingCyclesinteger | null

≥ 1 · ≤ 1 000

providerIdsstring[]

IDs of your payment providers (Settings → Payment providers).

sortOrderinteger

≥ -10000 · ≤ 10 000

Responses#

201The new package with its plans.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: package

namerequiredstring
descriptionrequiredstring | null
enabledrequiredboolean
sortOrderrequiredinteger
defaultProviderIdrequiredstring | null

Gateway used for gateway subscriptions when none is given.

plansPlan[]

Sorted by sortOrder, then price.

Show fields
plans fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0001pkg0001abcd",
  "object": "package",
  "name": "Acme Cloud",
  "description": "Hosted project management",
  "enabled": true,
  "sortOrder": 0,
  "defaultProviderId": "cmg1p0v1d0001prov0001abcd",
  "plans": [
    {
      "id": "cmg4p1a2b0002pln0001abcd",
      "object": "plan",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "name": "Pro",
      "description": "For growing teams",
      "features": [
        "Unlimited projects",
        "Priority support"
      ],
      "hasCallToAction": false,
      "callToActionUrl": null,
      "hasContactUs": false,
      "enabled": true,
      "frequency": "monthly",
      "amount": 499,
      "setupFee": 0,
      "currency": "ZAR",
      "trialDays": 14,
      "billingCycles": null,
      "providerIds": [],
      "sortOrder": 1,
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed, e.g. unknown provider, invalid currency, or a call-to-action plan without a URL.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Payment provider not found"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
409Idempotency-Key reused with a different body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/packages" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Cloud",
    "description": "Hosted project management",
    "plans": [
      {
        "name": "Pro",
        "frequency": "monthly",
        "amount": 499,
        "trialDays": 14,
        "features": [
          "Unlimited projects",
          "Priority support"
        ]
      }
    ]
  }'

Get a package#

GET/api/v1/packages/{id}

The package with all its plans (enabled and disabled). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The package.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: package

namerequiredstring
descriptionrequiredstring | null
enabledrequiredboolean
sortOrderrequiredinteger
defaultProviderIdrequiredstring | null

Gateway used for gateway subscriptions when none is given.

plansPlan[]

Sorted by sortOrder, then price.

Show fields
plans fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0001pkg0001abcd",
  "object": "package",
  "name": "Acme Cloud",
  "description": "Hosted project management",
  "enabled": true,
  "sortOrder": 0,
  "defaultProviderId": "cmg1p0v1d0001prov0001abcd",
  "plans": [
    {
      "id": "cmg4p1a2b0002pln0001abcd",
      "object": "plan",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "name": "Pro",
      "description": "For growing teams",
      "features": [
        "Unlimited projects",
        "Priority support"
      ],
      "hasCallToAction": false,
      "callToActionUrl": null,
      "hasContactUs": false,
      "enabled": true,
      "frequency": "monthly",
      "amount": 499,
      "setupFee": 0,
      "currency": "ZAR",
      "trialDays": 14,
      "billingCycles": null,
      "providerIds": [],
      "sortOrder": 1,
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
404No package with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Package not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a package#

PATCH/api/v1/packages/{id}

Partial update of name, description, enabled, sortOrder and defaultProviderId. Unknown fields are rejected. Idempotency-Key is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
namestring

1–120 chars

descriptionstring | null

max 2000 chars

enabledboolean

default true

sortOrderinteger

≥ -10000 · ≤ 10 000

defaultProviderIdstring | null

One of your payment providers.

Responses#

200The updated package.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: package

namerequiredstring
descriptionrequiredstring | null
enabledrequiredboolean
sortOrderrequiredinteger
defaultProviderIdrequiredstring | null

Gateway used for gateway subscriptions when none is given.

plansPlan[]

Sorted by sortOrder, then price.

Show fields
plans fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0001pkg0001abcd",
  "object": "package",
  "name": "Acme Cloud",
  "description": "Hosted project management",
  "enabled": true,
  "sortOrder": 0,
  "defaultProviderId": "cmg1p0v1d0001prov0001abcd",
  "plans": [
    {
      "id": "cmg4p1a2b0002pln0001abcd",
      "object": "plan",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "name": "Pro",
      "description": "For growing teams",
      "features": [
        "Unlimited projects",
        "Priority support"
      ],
      "hasCallToAction": false,
      "callToActionUrl": null,
      "hasContactUs": false,
      "enabled": true,
      "frequency": "monthly",
      "amount": 499,
      "setupFee": 0,
      "currency": "ZAR",
      "trialDays": 14,
      "billingCycles": null,
      "providerIds": [],
      "sortOrder": 1,
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No package with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Package not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Project management for teams",
    "sortOrder": 1
  }'

Disable a package#

DELETE/api/v1/packages/{id}

Disables the package (enabled: false) so it can't be subscribed to. Nothing is deleted and existing subscriptions keep billing. Re-enable it with PATCH.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The disabled package.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: package

namerequiredstring
descriptionrequiredstring | null
enabledrequiredboolean
sortOrderrequiredinteger
defaultProviderIdrequiredstring | null

Gateway used for gateway subscriptions when none is given.

plansPlan[]

Sorted by sortOrder, then price.

Show fields
plans fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0001pkg0001abcd",
  "object": "package",
  "name": "Acme Cloud",
  "description": "Hosted project management",
  "enabled": false,
  "sortOrder": 0,
  "defaultProviderId": "cmg1p0v1d0001prov0001abcd",
  "plans": [
    {
      "id": "cmg4p1a2b0002pln0001abcd",
      "object": "plan",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "name": "Pro",
      "description": "For growing teams",
      "features": [
        "Unlimited projects",
        "Priority support"
      ],
      "hasCallToAction": false,
      "callToActionUrl": null,
      "hasContactUs": false,
      "enabled": true,
      "frequency": "monthly",
      "amount": 499,
      "setupFee": 0,
      "currency": "ZAR",
      "trialDays": 14,
      "billingCycles": null,
      "providerIds": [],
      "sortOrder": 1,
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No package with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Package not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X DELETE "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Add a plan to a package#

POST/api/v1/packages/{id}/plans

Creates a plan in the package. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
namerequiredstring

1–120 chars

codestring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

descriptionstring | null

max 2000 chars

featuresstring[]
hasCallToActionboolean

Requires callToActionUrl.

callToActionUrlstring | null

http(s) URL.

max 1000 chars

hasContactUsboolean
enabledboolean

default true

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

0 is allowed: free plans activate without a payment.

≥ 0 · ≤ 100 000 000

setupFeenumber

≥ 0 · ≤ 100 000 000

currencystring

ISO 4217 code; default ZAR.

trialDaysinteger

≥ 0 · ≤ 730

billingCyclesinteger | null

≥ 1 · ≤ 1 000

providerIdsstring[]

IDs of your payment providers (Settings → Payment providers).

sortOrderinteger

≥ -10000 · ≤ 10 000

Responses#

201The new plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0003pln0002abcd",
  "object": "plan",
  "packageId": "cmg4p1a2b0001pkg0001abcd",
  "name": "Team (annual)",
  "description": null,
  "features": [
    "Up to 25 users"
  ],
  "hasCallToAction": false,
  "callToActionUrl": null,
  "hasContactUs": false,
  "enabled": true,
  "frequency": "annually",
  "amount": 4990,
  "setupFee": 0,
  "currency": "ZAR",
  "trialDays": 0,
  "billingCycles": null,
  "providerIds": [],
  "sortOrder": 1,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "currency must be a 3-letter ISO code"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No package with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Package not found"
}
409Idempotency-Key reused with a different body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd/plans" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team (annual)",
    "frequency": "annually",
    "amount": 4990,
    "setupFee": 0,
    "trialDays": 0,
    "features": [
      "Up to 25 users"
    ]
  }'

List plans (find one by code)#

GET/api/v1/plans

Plans across your packages in sort order. code finds the plan with your code (at most one). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Query parameters#

Query parameters
FieldTypeDescription
codestring

Exact plan code.

packageIdstring
enabledstring

One of: true, false

limitinteger

1-100, default 50.

≥ 1 · ≤ 100 · default 50

Responses#

200Plans.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredPlan[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/plans?code=acmehosting%3Apro%3Amonthly" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a plan#

GET/api/v1/plans/{id}

One plan. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0002pln0001abcd",
  "object": "plan",
  "packageId": "cmg4p1a2b0001pkg0001abcd",
  "name": "Pro",
  "description": "For growing teams",
  "features": [
    "Unlimited projects",
    "Priority support"
  ],
  "hasCallToAction": false,
  "callToActionUrl": null,
  "hasContactUs": false,
  "enabled": true,
  "frequency": "monthly",
  "amount": 499,
  "setupFee": 0,
  "currency": "ZAR",
  "trialDays": 14,
  "billingCycles": null,
  "providerIds": [],
  "sortOrder": 1,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z",
  "code": null
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
404No plan with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Plan not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a plan#

PATCH/api/v1/plans/{id}

Partial update. Price and frequency changes apply to new subscriptions only: existing subscriptions keep their price until they change plan. enabled: false hides the plan from checkout. Idempotency-Key is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
namestring

1–120 chars

codestring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

descriptionstring | null

max 2000 chars

featuresstring[]
hasCallToActionboolean

Requires callToActionUrl.

callToActionUrlstring | null

http(s) URL.

max 1000 chars

hasContactUsboolean
enabledboolean

default true

frequencystring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountnumber

0 is allowed: free plans activate without a payment.

≥ 0 · ≤ 100 000 000

setupFeenumber

≥ 0 · ≤ 100 000 000

currencystring

ISO 4217 code; default ZAR.

trialDaysinteger

≥ 0 · ≤ 730

billingCyclesinteger | null

≥ 1 · ≤ 1 000

providerIdsstring[]

IDs of your payment providers (Settings → Payment providers).

sortOrderinteger

≥ -10000 · ≤ 10 000

Responses#

200The updated plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: plan

packageIdrequiredstring
coderequiredstring | null

Your key for the plan, e.g. acmehosting:pro:monthly; unique in your organisation (409 plan_code_taken). Find it with GET /api/v1/plans?code= and subscribe with plan: <code>.

max 100 chars

namerequiredstring
descriptionrequiredstring | null
featuresrequiredstring[]

Feature bullet points shown on checkout pages and in the customer portal.

hasCallToActionrequiredboolean

The plan is shown with a button to callToActionUrl instead of being purchasable.

callToActionUrlrequiredstring | null
hasContactUsrequiredboolean

Show a “Contact us” option for the plan.

enabledrequiredboolean

Disabled plans can't be subscribed to; existing subscriptions keep billing.

frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

amountrequirednumber

Price per billing period (per unit of quantity).

setupFeerequirednumber

One-off fee added to the first charge (invoiced separately for debit orders).

currencyrequiredstring
trialDaysrequiredinteger

Free trial length for new subscriptions; 0 = no trial.

billingCyclesrequiredinteger | null

Fixed number of billing cycles; null = until cancelled.

providerIdsrequiredstring[]

Gateways customers may pay this plan with; empty = any enabled gateway.

sortOrderrequiredinteger
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4p1a2b0002pln0001abcd",
  "object": "plan",
  "packageId": "cmg4p1a2b0001pkg0001abcd",
  "name": "Pro",
  "description": "For growing teams",
  "features": [
    "Unlimited projects",
    "Priority support",
    "SSO"
  ],
  "hasCallToAction": false,
  "callToActionUrl": null,
  "hasContactUs": false,
  "enabled": true,
  "frequency": "monthly",
  "amount": 549,
  "setupFee": 0,
  "currency": "ZAR",
  "trialDays": 14,
  "billingCycles": null,
  "providerIds": [],
  "sortOrder": 1,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No plan with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Plan not found"
}
409`plan_code_taken`: another plan already has that `code`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/plans/cmg4p1a2b0002pln0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 549,
    "features": [
      "Unlimited projects",
      "Priority support",
      "SSO"
    ]
  }'

List customer subscriptions#

GET/api/v1/customer-subscriptions

Newest first, keyset paginated (limit, startingAfter -> hasMore, nextCursor). The response still has data as before. Requires the REST API and Recurring billing in your plan.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

Status, or a comma-separated list (e.g. active,past_due).

collectionMethodstring

Collection method, or a comma-separated list (e.g. external, or gateway,debit_order,invoice,manual for what CentraPoint collects).

planIdstring
packageIdstring
customerIdstring
customerExternalReferencestring

Your id of the customer (Customer.externalReference).

externalReferencestring

Exact match on your subscription ID.

nextBillingFromstring (date)

Next billing on or after (YYYY-MM-DD, SAST).

nextBillingTostring (date)

Next billing on or before (YYYY-MM-DD, SAST).

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200Subscriptions.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredCustomerSubscription[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
hasMorerequiredboolean
nextCursorrequiredstring | null
Example
{
  "data": [
    {
      "id": "cmg4s9d8e0005csb0001abcd",
      "object": "customer_subscription",
      "status": "trialing",
      "customer": {
        "id": "cmg2c0s7t0003cust0001abcd",
        "externalReference": "CRM-1001",
        "email": "[email protected]"
      },
      "plan": {
        "id": "cmg4p1a2b0002pln0001abcd",
        "name": "Pro",
        "packageId": "cmg4p1a2b0001pkg0001abcd",
        "packageName": "Acme Cloud"
      },
      "collectionMethod": "invoice",
      "quantity": 1,
      "amount": 499,
      "currency": "ZAR",
      "frequency": "monthly",
      "billingCycles": null,
      "cyclesBilled": 0,
      "startedAt": "2026-09-28T08:10:00.000Z",
      "trialEndsAt": "2026-10-12T08:10:00.000Z",
      "currentPeriodStart": null,
      "currentPeriodEnd": null,
      "nextBillingAt": "2026-10-12T08:10:00.000Z",
      "endsAt": null,
      "cancelAtPeriodEnd": false,
      "cancelledAt": null,
      "cancelReason": null,
      "pausedAt": null,
      "resumedAt": null,
      "dunningAttempts": 0,
      "gateway": null,
      "providerId": null,
      "paymentTokenId": null,
      "couponId": null,
      "externalReference": "SUB-CRM-1001-PRO",
      "metadata": {
        "crmDealId": "D-778"
      },
      "source": "api",
      "createdAt": "2026-09-28T08:10:00.000Z",
      "updatedAt": "2026-09-28T08:10:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of incomplete, trialing, active, past_due, paused, cancelled, expired"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Subscribe a customer to a plan#

POST/api/v1/customer-subscriptions

Creates a subscription (201). With a trial it starts trialing; otherwise incomplete until the first payment (setup fee + first period) completes, then active. A zero first charge activates at once. payment says what is due now and where the customer pays (payUrl). With an externalReference that already exists, the existing subscription is returned with 200 and its current payment state. Unless one side is an external (mirror) subscription and the other is not, or the existing one belongs to another customer: then 409 external_reference_conflict. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise). collectionMethod: external records a subscription your platform bills (mirror import): nothing is charged, emailed or sent as a webhook, payment.due is false and collectedByCentraPoint is false. dryRun: true validates the same way and answers 200 with CustomerSubscriptionDryRun without writing anything. The externalReference is unique per organisation, also for two requests at the same time (the second gets 200 and the first one's subscription).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring
customerobject | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
planIdstring

The plan id (or send plan).

planstring

Instead of planId: the plan's id or its code.

max 190 chars

collectionMethodrequiredstring

gateway: card via a gateway (first payment through a payment link; PayFast / Netcash Pay Now then bill it themselves). debit_order: a Netcash mandate (needs Debit orders; ZAR; monthly/quarterly/biannual/annual plans). invoice: an invoice per cycle (needs Invoicing). manual: an invoice per cycle that is not emailed; you collect and record the payment (needs Invoicing). external: your platform bills it and CentraPoint only records it (imports): needs externalReference and paidThrough (for status: trialing the trial end; trialEnd may replace it); may use disabled plans; providerId, mandateId, coupons, startDate, billingAnchorDay, trial / trialDays and non-addon items are refused (400).

One of: gateway, debit_order, invoice, manual, external

providerIdstring

Gateway or Netcash provider. Default: the package's default provider (gateway) or the mandate's (debit order).

quantityinteger

≥ 1 · ≤ 10 000 · default 1

couponCodestring

Needs Coupons in your plan; validated for the plan and customer.

1–50 chars

trialboolean

false skips the plan's free trial.

default true

trialDaysinteger

Overrides the plan's trial length.

≥ 0 · ≤ 730

mandateIdstring

debit_order only: an existing mandate of this customer with the plan's frequency, not linked to another subscription.

externalReferencestring

Your ID, unique per organisation (also for requests at the same time). Creating again with the same value returns the existing subscription (200, created: false), unless the existing one belongs to another customer or one of the two is external and the other is not (409 external_reference_conflict). Required for external, and it cannot be changed or removed later.

1–190 chars

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sendEmailboolean

Email the first invoice / payment request / trial confirmation. Never sent for external subscriptions.

default true

couponIdstring

Coupon by id (instead of couponCode).

startDatestring

YYYY-MM-DD (06:00 SAST) or ISO date-time. A future start makes the subscription scheduled: the trial / first charge starts then.

paidThroughstring

YYYY-MM-DD or ISO date-time. The customer already paid until then (e.g. moved from another billing system): active now, nothing charged, first renewal on this date. Not with startDate. external: the end of your platform's current period, sent on every import: in the future for active, may be in the past for past_due, and the trial end (future) for trialing (trialEnd may be sent instead of it or with it, on the same day).

billingAnchorDayinteger

Renewals fall on this day of the month; the first period is shortened to it and pro-rated. Monthly and longer plans; not for debit orders.

≥ 1 · ≤ 31

itemsSubscriptionItemInput[]

Add-ons (e.g. website alias x3 at 250), metered lines, one-time lines on the first charge.

Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
statusstring

external only: your platform's status (default active, or trialing when trialEnd is sent).

One of: active, trialing, past_due

currentPeriodStartstring

external only: start of your platform's current period (YYYY-MM-DD or ISO date-time), not in the future. Default: one billing cycle before paidThrough (now when paid further ahead).

trialEndstring

external with status: trialing: when your platform's trial ends (future). Optional when paidThrough carries the trial end; when both are sent they must be the same day (the time of trialEnd is used). Without status, sending trialEnd imports the row as trialing.

cancelAtPeriodEndboolean

external only: your platform will not renew it; the record ends, silently, at the period end.

dryRunboolean

Validate and preview only: 200 { dryRun, action, subscription }, nothing written, charged, emailed or sent, and no Idempotency-Key stored. The customer and plan must already exist (otherwise the create's 400 Customer not found / Plan not found); other errors are the create's own.

default false

Responses#

200A subscription with this externalReference already exists: returned unchanged with `created: false` and its current payment state. Or, with `dryRun: true`, the dry-run result.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.

CustomerSubscriptionCreated | CustomerSubscriptionDryRun

201Created (`created: true`). For a trial or an external subscription nothing is due.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
createdrequiredboolean

true (201) for a new subscription, false (200) when one with this externalReference existed.

paymentrequiredSubscriptionStartPayment

What is due now and how the customer pays it.

Show fields
payment fields
FieldTypeDescription
duerequiredboolean

Money is due before the subscription becomes active.

amountrequirednumber
currencyrequiredstring
methodrequiredstring

invoice: an invoice with a pay link was created. link: a (recurring) payment link. token: a stored card was charged. none: nothing to collect now (trial, free plan, gateway- or debit-order-collected). checkout: returned on a replay of an incomplete gateway subscription with no open payment request.

One of: none, invoice, link, token, checkout

payUrlrequiredstring | null

Send the customer here to pay.

invoiceIdrequiredstring | null
paymentLinkIdrequiredstring | null
transactionIdrequiredstring | null
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "trialing",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-12T08:10:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": null,
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z",
  "payment": {
    "due": false,
    "amount": 0,
    "currency": "ZAR",
    "method": "none",
    "payUrl": null,
    "invoiceId": null,
    "paymentLinkId": null,
    "transactionId": null
  },
  "created": true
}
400Validation failed: customer/plan/mandate/provider not found, inactive customer, disabled plan, invalid coupon, unsupported collection method for the plan, etc.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "This plan is not available"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403`plan_restricted`: no REST API or Recurring billing. `plan_limit`: the collection method needs Invoicing or Debit orders, which your plan lacks. `account_restricted`: the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_limit",
  "message": "Debit orders is not included in the Growth plan. Upgrade under Settings > Billing."
}
409`idempotency_conflict`: Idempotency-Key reused with a different body. `external_reference_conflict`: the `externalReference` belongs to another customer's subscription, or one of the two is an external (mirror) subscription and the other is not (a mirror of a subscription CentraPoint bills, or a create meant to let CentraPoint bill a mirrored one). `external_imports_unavailable`: `collectionMethod: external` (also a dry run) for a short time while CentraPoint is being updated (`GET /api/v1/me` says `capabilities.externalSubscriptions: false`); nothing was written, try again later.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
idempotencyConflict
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
externalReferenceConflict
{
  "error": "external_reference_conflict",
  "message": "externalReference acmehosting-sub:1042 belongs to a subscription with collectionMethod external, not invoice. To let CentraPoint bill it, cancel that record and create the new subscription with its own externalReference."
}
externalImportsUnavailable
{
  "error": "external_imports_unavailable",
  "message": "CentraPoint is being updated, so it does not accept subscriptions your platform bills (collectionMethod external) now. Nothing was written: try again later (GET /api/v1/me says capabilities.externalSubscriptions: true once it does)."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalReference": "acmehosting:user:1042"
    },
    "plan": "acmehosting:pro:monthly",
    "collectionMethod": "external",
    "paidThrough": "2026-10-31",
    "externalReference": "acmehosting-sub:1042",
    "sendEmail": false,
    "dryRun": true
  }'

Get a customer subscription#

GET/api/v1/customer-subscriptions/{id}

Add ?include=events for the timeline (latest 100 events). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Query parameters#

Query parameters
FieldTypeDescription
includestring

events adds the event timeline.

One of: events

Responses#

200The subscription.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "trialing",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-12T08:10:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": null,
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "Recurring billing is not included in your plan"
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a customer subscription#

PATCH/api/v1/customer-subscriptions/{id}

Changes metadata, externalReference or nextBillingAt. Sends subscription.updated. Unknown fields are rejected. Idempotency-Key is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
metadataMetadataInput | null

Replaces the whole map; null clears it.

externalReferencestring | null

Must not belong to another subscription. An external subscription's externalReference (its import key) cannot be changed or removed: 409 external_subscription.

max 190 chars

nextBillingAtstring (date-time)

Next renewal / charge. For card subscriptions the gateway bills itself, only where the gateway can move the date (PayFast).

billingAnchorDayinteger | null

Day of month later renewals fall on; null clears it.

≥ 1 · ≤ 31

Responses#

200The updated subscription.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "trialing",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-15T06:00:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-15T06:00:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": null,
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Debit order dates follow the mandate's debit day - edit the mandate instead"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`external_subscription`: `nextBillingAt` / `billingAnchorDay` on a subscription your platform bills (use sync-period), or changing or removing its `externalReference`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nextBillingAt": "2026-10-15T08:00:00+02:00"
  }'

Pause a customer subscription#

POST/api/v1/customer-subscriptions/{id}/pause

Stops billing until resumed. Allowed from active or past_due; pausing a paused subscription returns it unchanged. Linked debit order mandates are paused too; gateway-billed subscriptions are paused at the gateway first (PayFast, Netcash Pay Now), and gateways that can't pause return 400. Sends subscription.paused. No body.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The subscription after the pause.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "paused",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-12T08:10:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": "2026-11-02T09:00:00.000Z",
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
400Not allowed from the current status, or the gateway refused. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Only active subscriptions can be paused (this one is trialing)"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/pause" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Resume a customer subscription#

POST/api/v1/customer-subscriptions/{id}/resume

Resumes a paused subscription (resuming an active one returns it unchanged). Billing restarts at the end of the already-paid period, or now if it has passed; the status returns to active (or past_due / incomplete if it was). Sends subscription.resumed. No body.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The subscription after the resume.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "active",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-12T08:10:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": null,
  "resumedAt": "2026-11-10T09:00:00.000Z",
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
400Not allowed from the current status, or the gateway refused. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Only active subscriptions can be paused (this one is trialing)"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/resume" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Cancel a customer subscription#

POST/api/v1/customer-subscriptions/{id}/cancel

Cancels now, or with atPeriodEnd: true at the end of the paid period (trial end for trials). Gateway billing is stopped at the gateway first; if the gateway refuses, nothing changes (400). Cancelling a cancelled or expired subscription returns it unchanged. Immediate cancellation sends subscription.cancelled (and cancels unpaid first invoices of incomplete/trialing subscriptions); a scheduled one sends subscription.updated with cancelAtPeriodEnd: true. sendEmail: false cancels without emailing the customer; external subscriptions are always cancelled silently.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

Request body fields
FieldTypeDescription
atPeriodEndboolean

Cancel when the paid period (or trial) ends instead of now.

default false

reasonstring

max 1000 chars

whenstring

Alternative to atPeriodEnd.

One of: now, period_end

sendEmailboolean

false: no cancellation email to the customer. External subscriptions are always cancelled silently.

default true

Responses#

200The subscription after the cancellation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "active",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0002pln0001abcd",
    "name": "Pro",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": null,
  "endsAt": "2026-11-12T08:10:00.000Z",
  "cancelAtPeriodEnd": true,
  "cancelledAt": null,
  "cancelReason": "Moving to another provider",
  "pausedAt": null,
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
400Not allowed from the current status, or the gateway refused. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "PayFast did not accept the cancellation. The subscription was not cancelled."
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "atPeriodEnd": true,
    "reason": "Moving to another provider"
  }'

Change plan#

POST/api/v1/customer-subscriptions/{id}/change-plan

Changes plan, quantity and/or the recurring add-on items. proration: none (default, backwards compatible: new price from the next renewal), now (charge or credit the rest of the period; a frequency change starts a new period now), next_renewal (scheduled, see pendingChange). Gateways that bill the card themselves change the amount in place when they can (PayFast, Netcash Pay Now), otherwise the change is refused (use POST /api/v1/subscriptions/{id}/update to replace the card subscription). Sends subscription.plan_changed (or subscription.updated for items / scheduled changes) with invoiceId of any proration invoice. External subscriptions: the change is recorded without proration (proration is always none, nothing is charged) and may move to disabled plans.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
planIdstring
quantityinteger

≥ 1 · ≤ 10 000

itemsSubscriptionItemInput[]

The complete list of recurring lines (addon / metered) after the change; matched by code. Omit to keep the current ones.

Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
prorationstring

none: switch now, the new price applies from the next renewal. now: switch now and charge (or credit) the difference for the rest of the period; a frequency change starts a new period now. next_renewal: switch at the next renewal (pendingChange).

One of: none, now, next_renewal

default "none"

invoiceNowboolean

now: invoice / charge a positive difference immediately; false adds it to the next renewal. Credits always go to the next renewal.

default true

Responses#

200The subscription after the plan change.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
changeSubscriptionChangePreview
Show fields
change fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

chargeobject | null

Proration charge issued now: {method: invoice, invoiceId, invoiceNumber, payUrl} or {method: token, transactionId, status}.

Example
{
  "id": "cmg4s9d8e0005csb0001abcd",
  "object": "customer_subscription",
  "status": "trialing",
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001",
    "email": "[email protected]"
  },
  "plan": {
    "id": "cmg4p1a2b0003pln0002abcd",
    "name": "Team (annual)",
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "packageName": "Acme Cloud"
  },
  "collectionMethod": "invoice",
  "quantity": 1,
  "amount": 4990,
  "currency": "ZAR",
  "frequency": "annually",
  "billingCycles": null,
  "cyclesBilled": 0,
  "startedAt": "2026-09-28T08:10:00.000Z",
  "trialEndsAt": "2026-10-12T08:10:00.000Z",
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "nextBillingAt": "2026-10-12T08:10:00.000Z",
  "endsAt": null,
  "cancelAtPeriodEnd": false,
  "cancelledAt": null,
  "cancelReason": null,
  "pausedAt": null,
  "resumedAt": null,
  "dunningAttempts": 0,
  "gateway": null,
  "providerId": null,
  "paymentTokenId": null,
  "couponId": null,
  "externalReference": "SUB-CRM-1001-PRO",
  "metadata": {
    "crmDealId": "D-778"
  },
  "source": "api",
  "createdAt": "2026-09-28T08:10:00.000Z",
  "updatedAt": "2026-09-28T08:10:00.000Z"
}
400Not allowed from the current status, or the gateway refused. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "The new plan is billed in USD, the subscription in ZAR"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No subscription with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Subscription not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/change-plan" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "cmg4p1a2b0003pln0001abcd",
    "items": [
      {
        "code": "website_alias",
        "description": "Website alias",
        "unitAmount": 250,
        "quantity": 3
      }
    ],
    "proration": "now"
  }'

List products#

GET/api/v1/products

Your product catalogue in name order.

Query parameters#

Query parameters
FieldTypeDescription
enabledstring

Only enabled (true) or disabled (false) products.

One of: true, false

billingTypestring

Filter by billing type.

One of: once, recurring

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Products.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredProduct[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: product

skurequiredstring | null
namerequiredstring
descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring
billingTyperequiredstring

One of: once, recurring

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

taxablerequiredboolean
enabledrequiredboolean
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg4r7q6p0004prd0001abcd",
      "object": "product",
      "sku": "SUP-HR",
      "name": "Support hour",
      "description": "One hour of remote support",
      "amount": 650,
      "currency": "ZAR",
      "billingType": "once",
      "frequency": null,
      "taxable": true,
      "enabled": true,
      "createdAt": "2026-09-28T08:00:00.000Z",
      "updatedAt": "2026-09-28T08:00:00.000Z"
    }
  ]
}
400Invalid billingType.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "billingType must be once or recurring"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a product#

POST/api/v1/products

Creates a catalogue product. Recurring products need a frequency and a plan with Recurring billing.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
skustring | null

max 50 chars

namerequiredstring

1–100 chars

descriptionstring | null

max 2000 chars

amountrequirednumber

> 0 · ≤ 100 000 000

currencystring

ISO 4217; default ZAR.

billingTypestring

recurring needs a frequency and a plan with recurring billing.

One of: once, recurring

default "once"

frequencystring | null

One of: monthly, quarterly, biannually, annually, null

taxableboolean

default true

enabledboolean

default true

Responses#

201The new product.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: product

skurequiredstring | null
namerequiredstring
descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring
billingTyperequiredstring

One of: once, recurring

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

taxablerequiredboolean
enabledrequiredboolean
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4r7q6p0004prd0001abcd",
  "object": "product",
  "sku": "SUP-HR",
  "name": "Support hour",
  "description": "One hour of remote support",
  "amount": 650,
  "currency": "ZAR",
  "billingType": "once",
  "frequency": null,
  "taxable": true,
  "enabled": true,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed (e.g. recurring without frequency, invalid currency, unknown field).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Recurring products need a frequency"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
409Idempotency-Key reused with a different body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/products" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SUP-HR",
    "name": "Support hour",
    "description": "One hour of remote support",
    "amount": 650
  }'

Get a product#

GET/api/v1/products/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The product.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: product

skurequiredstring | null
namerequiredstring
descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring
billingTyperequiredstring

One of: once, recurring

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

taxablerequiredboolean
enabledrequiredboolean
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4r7q6p0004prd0001abcd",
  "object": "product",
  "sku": "SUP-HR",
  "name": "Support hour",
  "description": "One hour of remote support",
  "amount": 650,
  "currency": "ZAR",
  "billingType": "once",
  "frequency": null,
  "taxable": true,
  "enabled": true,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No product with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Product not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a product#

PATCH/api/v1/products/{id}

Partial update; null clears sku/description. Switching to billingType: "recurring" needs a frequency and Recurring billing; switching to once clears the frequency. Idempotency-Key is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
skustring | null

max 50 chars

namestring

1–100 chars

descriptionstring | null

max 2000 chars

amountnumber

> 0 · ≤ 100 000 000

currencystring

ISO 4217; default ZAR.

billingTypestring

recurring needs a frequency and a plan with recurring billing.

One of: once, recurring

default "once"

frequencystring | null

One of: monthly, quarterly, biannually, annually, null

taxableboolean

default true

enabledboolean

default true

Responses#

200The updated product.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: product

skurequiredstring | null
namerequiredstring
descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring
billingTyperequiredstring

One of: once, recurring

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

taxablerequiredboolean
enabledrequiredboolean
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4r7q6p0004prd0001abcd",
  "object": "product",
  "sku": "SUP-HR",
  "name": "Support hour",
  "description": "One hour of remote support",
  "amount": 700,
  "currency": "ZAR",
  "billingType": "once",
  "frequency": null,
  "taxable": true,
  "enabled": true,
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Recurring products need a frequency"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, plan feature missing, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No product with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Product not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/products/cmg4r7q6p0004prd0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 700,
    "enabled": true
  }'

List EFT orders#

GET/api/v1/eft-orders

Newest first.

Query parameters#

Query parameters
FieldTypeDescription
externalReferencestring
customerIdstring
statusstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200EFT orders.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredEftOrder[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg3e1f2t0009eft0001abcd",
      "reference": "EFT-7K3Q9P2M",
      "status": "awaiting_review",
      "amount": 1250,
      "currency": "ZAR",
      "description": "Order #1001",
      "externalReference": "ORDER-1001",
      "metadata": {
        "cartId": "c_8841"
      },
      "customer": {
        "id": "cmg2c0s7t0003cust0001abcd",
        "externalReference": "CRM-1001"
      },
      "bankDetails": {
        "bankName": "FNB",
        "accountName": "Example Traders (Pty) Ltd",
        "accountNumber": "62000000000",
        "branchCode": "250655",
        "accountType": "current"
      },
      "paymentReference": "EFT-7K3Q9P2M",
      "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
      "proofs": [
        {
          "id": "cmg3p0r0f0011prf0001abcd",
          "fileName": "proof.pdf",
          "contentType": "application/pdf",
          "size": 184213,
          "source": "payer",
          "createdAt": "2026-09-25T09:12:00.000Z"
        }
      ],
      "rejectionReason": null,
      "expiresAt": "2026-10-02T08:00:00.000Z",
      "reviewedAt": null,
      "paidAt": null,
      "createdAt": "2026-09-25T08:00:00.000Z"
    }
  ]
}
400Unknown status.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of awaiting_payment, awaiting_review, paid, rejected, expired, cancelled"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or payment links, or the account is read-only (writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create an EFT order#

POST/api/v1/eft-orders

Issues a unique deposit reference and returns your bank details for the payer (201). Requires an enabled Manual EFT gateway, the Payment links feature and API access. Idempotent on externalReference for open orders (200).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountrequirednumber

> 0 · ≤ 100 000 000

currencystring

One of ZAR, NAD, BWP, LSL, SZL.

default "ZAR"

customerIdstring
customerobject | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
descriptionstring

max 1000 chars

externalReferencestring

Your ID. If an open order (awaiting_payment, awaiting_review or rejected) with this reference exists, it is returned with 200 instead of creating another; a different amount or currency is a 400.

1–190 chars

metadataMetadataInput

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

expiresAtstring (date-time)

At least 5 minutes and at most 90 days ahead. Default: the gateway's expiry days (7 by default).

notifyPayerboolean

Email the customer the bank details and payUrl when the order is created. Requires a customer with an email address (400 otherwise). Not re-sent when an existing open order is returned.

default false

Responses#

200An open order with this externalReference already existed; returned unchanged.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "id": "cmg3e1f2t0009eft0001abcd",
  "reference": "EFT-7K3Q9P2M",
  "status": "awaiting_payment",
  "amount": 1250,
  "currency": "ZAR",
  "description": "Order #1001",
  "externalReference": "ORDER-1001",
  "metadata": {
    "cartId": "c_8841"
  },
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001"
  },
  "bankDetails": {
    "bankName": "FNB",
    "accountName": "Example Traders (Pty) Ltd",
    "accountNumber": "62000000000",
    "branchCode": "250655",
    "accountType": "current"
  },
  "paymentReference": "EFT-7K3Q9P2M",
  "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
  "proofs": [],
  "rejectionReason": null,
  "expiresAt": "2026-10-02T08:00:00.000Z",
  "reviewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-25T08:00:00.000Z"
}
201Order created.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "id": "cmg3e1f2t0009eft0001abcd",
  "reference": "EFT-7K3Q9P2M",
  "status": "awaiting_payment",
  "amount": 1250,
  "currency": "ZAR",
  "description": "Order #1001",
  "externalReference": "ORDER-1001",
  "metadata": {
    "cartId": "c_8841"
  },
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001"
  },
  "bankDetails": {
    "bankName": "FNB",
    "accountName": "Example Traders (Pty) Ltd",
    "accountNumber": "62000000000",
    "branchCode": "250655",
    "accountType": "current"
  },
  "paymentReference": "EFT-7K3Q9P2M",
  "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
  "proofs": [],
  "rejectionReason": null,
  "expiresAt": "2026-10-02T08:00:00.000Z",
  "reviewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-25T08:00:00.000Z"
}
400Validation failed, Manual EFT not set up or not available, unsupported currency, customer not found, expiresAt out of range, or an open order for this externalReference has a different amount. `notifyPayer` without a customer email address.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Manual EFT is not set up. Add a 'Manual EFT (bank transfer)' gateway with your bank details under Settings > Payment providers."
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan lacks the API or payment links, monthly transaction limit reached (`plan_limit`), or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1250,
    "customer": {
      "externalReference": "CRM-1001"
    },
    "description": "Order #1001",
    "externalReference": "ORDER-1001",
    "metadata": {
      "cartId": "c_8841"
    },
    "notifyPayer": true
  }'

Get an EFT order#

GET/api/v1/eft-orders/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The order.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "id": "cmg3e1f2t0009eft0001abcd",
  "reference": "EFT-7K3Q9P2M",
  "status": "awaiting_review",
  "amount": 1250,
  "currency": "ZAR",
  "description": "Order #1001",
  "externalReference": "ORDER-1001",
  "metadata": {
    "cartId": "c_8841"
  },
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001"
  },
  "bankDetails": {
    "bankName": "FNB",
    "accountName": "Example Traders (Pty) Ltd",
    "accountNumber": "62000000000",
    "branchCode": "250655",
    "accountType": "current"
  },
  "paymentReference": "EFT-7K3Q9P2M",
  "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
  "proofs": [
    {
      "id": "cmg3p0r0f0011prf0001abcd",
      "fileName": "proof.pdf",
      "contentType": "application/pdf",
      "size": 184213,
      "source": "payer",
      "createdAt": "2026-09-25T09:12:00.000Z"
    }
  ],
  "rejectionReason": null,
  "expiresAt": "2026-10-02T08:00:00.000Z",
  "reviewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-25T08:00:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or payment links, or the account is read-only (writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No EFT order with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "EFT order not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Upload proof of payment#

POST/api/v1/eft-orders/{id}/proof

multipart/form-data with one file field. The type is detected from the file's bytes: PDF, PNG or JPEG only; at most 10 MB; at most 10 files per order. Allowed while the order is awaiting_payment, awaiting_review or rejected (and not past its expiry, unless already in review). Moves the order to awaiting_review, notifies your staff and sends eft.proof_received. Uploading an identical file again is harmless (deduplicated by content hash). The Idempotency-Key header is not used on this endpoint.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

multipart/form-data · required

Multipart fields
FieldTypeDescription
filerequiredstring (binary)

PDF, PNG or JPEG, max 10 MB.

Responses#

200The order after the upload.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "id": "cmg3e1f2t0009eft0001abcd",
  "reference": "EFT-7K3Q9P2M",
  "status": "awaiting_review",
  "amount": 1250,
  "currency": "ZAR",
  "description": "Order #1001",
  "externalReference": "ORDER-1001",
  "metadata": {
    "cartId": "c_8841"
  },
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001"
  },
  "bankDetails": {
    "bankName": "FNB",
    "accountName": "Example Traders (Pty) Ltd",
    "accountNumber": "62000000000",
    "branchCode": "250655",
    "accountType": "current"
  },
  "paymentReference": "EFT-7K3Q9P2M",
  "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
  "proofs": [
    {
      "id": "cmg3p0r0f0011prf0001abcd",
      "fileName": "proof.pdf",
      "contentType": "application/pdf",
      "size": 184213,
      "source": "payer",
      "createdAt": "2026-09-25T09:12:00.000Z"
    }
  ],
  "rejectionReason": null,
  "expiresAt": "2026-10-02T08:00:00.000Z",
  "reviewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-25T08:00:00.000Z"
}
400Missing file, empty or unsupported file type, order not open or expired, or too many proofs.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Proof must be a PDF, PNG or JPEG file"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or payment links, or the account is read-only (writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No EFT order with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "EFT order not found"
}
413File larger than 10 MB.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "File is larger than 10 MB"
}
415Body is not multipart/form-data.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Send multipart/form-data with a 'file' field"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/proof"   -H "Authorization: Bearer $CENTRAPOINT_API_KEY"   -F "[email protected];type=application/pdf"

Download a proof of payment#

GET/api/v1/eft-orders/{id}/proofs/{proofId}

One proof-of-payment file of an EFT order, exactly as it was uploaded (by the payer on the EFT payment page, or through Upload proof of payment). proofId is an id from the order's proofs list. The Content-Type is the type detected at upload (PDF, PNG or JPEG); the file is sent as an attachment with Cache-Control: private, no-store. Requires payment links in your plan.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring
proofIdrequiredstring

Responses#

200The file.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Content-Disposition – `attachment; filename="…"` with the file name as uploaded.
  • X-Proof-Sha256 – SHA-256 of the file (hex).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or payment links.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No such proof on this EFT order in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Proof not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/proofs/cmg3p0r0f0011prf0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Cancel an EFT order#

POST/api/v1/eft-orders/{id}/cancel

Cancels an unpaid order (awaiting_payment, awaiting_review or rejected) and its pending transaction, and sends eft.cancelled and payment.cancelled. Cancelling a cancelled order returns it unchanged. No body is required.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json

object

Responses#

200The cancelled order.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
200 response fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example
{
  "id": "cmg3e1f2t0009eft0001abcd",
  "reference": "EFT-7K3Q9P2M",
  "status": "cancelled",
  "amount": 1250,
  "currency": "ZAR",
  "description": "Order #1001",
  "externalReference": "ORDER-1001",
  "metadata": {
    "cartId": "c_8841"
  },
  "customer": {
    "id": "cmg2c0s7t0003cust0001abcd",
    "externalReference": "CRM-1001"
  },
  "bankDetails": {
    "bankName": "FNB",
    "accountName": "Example Traders (Pty) Ltd",
    "accountNumber": "62000000000",
    "branchCode": "250655",
    "accountType": "current"
  },
  "paymentReference": "EFT-7K3Q9P2M",
  "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
  "proofs": [],
  "rejectionReason": null,
  "expiresAt": "2026-10-02T08:00:00.000Z",
  "reviewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-25T08:00:00.000Z"
}
400The order is paid or expired.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "EFT order is paid"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or payment links, or the account is read-only (writes).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No EFT order with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "EFT order not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

List transactions#

GET/api/v1/transactions

Payments in your organisation, newest first, with keyset pagination (limit, startingAfter). Use GET /api/v1/transactions/{reference} for the full detail of one payment.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

Filter by status.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

typestring

Filter by type.

One of: once, recurring, invoice

customerIdstring

Filter by customer.

invoiceIdstring

Filter by invoice.

paymentLinkIdstring

Filter by payment link.

subscriptionIdstring

Filter by customer subscription.

fromstring (date)

Start date (YYYY-MM-DD, SAST, inclusive) on the created date.

tostring (date)

End date (YYYY-MM-DD, SAST, inclusive) on the created date.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of transactions.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredTransactionSummary[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

typerequiredstring

once, recurring, invoice, debit_order or eft.

amountrequirednumber
feerequirednumber | null
netrequirednumber | null
taxAmountrequirednumber | null
discountAmountrequirednumber | null
currencyrequiredstring
gatewayrequiredstring
sandboxrequiredboolean

true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives.

descriptionrequiredstring | null
providerRefrequiredstring | null
payerNamerequiredstring | null
payerEmailrequiredstring | null
customerIdrequiredstring | null
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idstring
numberstring
paymentLinkIdrequiredstring | null
subscriptionIdrequiredstring | null

Customer subscription the payment belongs to.

refundedAmountrequirednumber
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
receiptUrlrequiredstring | null

Receipt URL for completed (or refunded) payments.

hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg2t1x2y0009txn0001abcd",
      "reference": "CP-20260925-9F3A1C7B",
      "status": "complete",
      "type": "invoice",
      "amount": 1150,
      "fee": 40.25,
      "net": 1109.75,
      "taxAmount": 150,
      "discountAmount": null,
      "currency": "ZAR",
      "gateway": "payfast",
      "description": "Invoice INV-00042",
      "providerRef": "1234567",
      "payerName": "Thandi Nkosi",
      "payerEmail": "[email protected]",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "invoice": {
        "id": "cmg2i4n5v0004inv0001abcd",
        "number": "INV-00042"
      },
      "paymentLinkId": null,
      "subscriptionId": null,
      "refundedAmount": 0,
      "paidAt": "2026-09-25T08:14:03.000Z",
      "createdAt": "2026-09-25T08:12:40.000Z",
      "receiptUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd"
    }
  ],
  "hasMore": true,
  "nextCursor": "cmg2t1x2y0009txn0001abcd"
}
400Invalid status/type, bad date format, or an unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of pending, complete, failed, cancelled, refunded, partially_refunded"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/transactions?status=complete" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a transaction by reference#

GET/api/v1/transactions/{reference}

Returns the current state of a payment in your organisation, looked up by its CentraPoint payment reference. Transactions in other organisations are reported as not found.

Path parameters#

Path parameters
FieldTypeDescription
referencerequiredstring

CentraPoint payment reference, e.g. CP-20260925-9F3A1C7B. Recurring renewals use <original reference>-<gateway payment id>; debit order collections use <mandate account reference>-<YYYYMMDD>, e.g. DO7F3A1C9B2E-20261001.

Responses#

200The transaction.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
referencerequiredstring

CentraPoint payment reference.

statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountrequirednumber

Gross amount in major units.

feerequirednumber | null

Gateway fee, when the gateway reports it.

netrequirednumber | null

Amount after the gateway fee, when reported.

currencyrequiredstring
typerequiredstring

invoice when the link was for an invoice, recurring for subscription charges, debit_order for Netcash debit order collections, otherwise once. eft for Manual EFT orders. card_setup for the R1.00 payment that saves a card, card_debit for a saved card charged by the bank (pending until the bank confirms).

One of: once, recurring, invoice, debit_order, eft, card_setup, card_debit

gatewayrequiredstring

Gateway type that processed the payment, e.g. payfast, paystack, mpesa, netcash.

sandboxrequiredboolean

true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives.

descriptionrequiredstring | null

Usually the payment link title.

providerRefrequiredstring | null

The gateway's own ID for the payment (e.g. PayFast pf_payment_id).

payerEmailrequiredstring | null
paymentLinkIdrequiredstring | null

ID of the payment link the payment was made through, if any.

externalReferencerequiredstring | null

The payment link's externalReference, the EFT order's, or the one sent when charging a saved card (POST /api/v1/customers/{id}/cards/{cardId}/charges).

eftOrderIdrequiredstring | null

EFT order the payment belongs to (Manual EFT).

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

renewalrequiredboolean

True for later collections of a subscription.

parentReferencerequiredstring | null

For renewals: reference of the first payment.

subscriptionIdrequiredstring | null

Subscription started by the payment link, if any.

refundedAmountrequirednumber

Total of non-failed refunds, 0 if none.

refundsrequiredRefund[]

Refunds recorded for this payment, oldest first. Failed refunds are excluded.

Show fields
refunds fields
FieldTypeDescription
refundNumberrequiredstring
amountrequirednumber
currencyrequiredstring
statusrequiredstring

Failed refunds are not returned.

One of: pending, processed

processedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
invoicerequirednull | object
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
invoiceNumberrequiredstring

Same as number; kept for compatibility.

statusrequiredstring

One of: draft, sent, paid, overdue, cancelled

externalReferencerequiredstring | null
paidAtrequiredstring (date-time) | null

Set when the transaction becomes complete.

createdAtrequiredstring (date-time)
Example
{
  "reference": "CP-20260925-9F3A1C7B",
  "status": "partially_refunded",
  "amount": 499,
  "fee": 14.47,
  "net": 484.53,
  "currency": "ZAR",
  "type": "once",
  "gateway": "payfast",
  "description": "Website hosting - October",
  "providerRef": "2458761",
  "payerEmail": "[email protected]",
  "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
  "externalReference": "ORDER-1001",
  "eftOrderId": null,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "renewal": false,
  "parentReference": null,
  "subscriptionId": null,
  "refundedAmount": 100,
  "refunds": [
    {
      "refundNumber": "REF-7C21A9F0",
      "amount": 100,
      "currency": "ZAR",
      "status": "processed",
      "processedAt": "2026-09-26T09:30:00.000Z",
      "createdAt": "2026-09-26T09:29:41.000Z"
    }
  ],
  "invoice": null,
  "paidAt": "2026-09-25T08:14:03.512Z",
  "createdAt": "2026-09-25T08:12:47.020Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No transaction with this reference exists in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Transaction not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/transactions/CP-20260925-9F3A1C7B" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List receipts#

GET/api/v1/receipts

Completed payments (including those later refunded) as receipts, newest payment first. Keyset pagination with limit and startingAfter.

Query parameters#

Query parameters
FieldTypeDescription
customerIdstring

Filter by customer.

invoiceIdstring

Filter by invoice.

fromstring (date)

Start date (YYYY-MM-DD, SAST, inclusive) on the payment date.

tostring (date)

End date (YYYY-MM-DD, SAST, inclusive) on the payment date.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of receipts.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredReceipt[]
Show fields
data fields
FieldTypeDescription
idrequiredstring

Transaction ID.

objectrequiredstring

One of: receipt

receiptNumberrequiredstring

The payment reference.

referencerequiredstring
statusrequiredstring

One of: complete, partially_refunded, refunded

amountrequirednumber
currencyrequiredstring
taxAmountrequirednumber | null

Tax included in the payment, when known.

discountAmountrequirednumber | null
refundedAmountrequirednumber
descriptionrequiredstring | null
payerNamerequiredstring | null
payerEmailrequiredstring | null
customerIdrequiredstring | null
paymentMethodrequiredstring

Display name of the payment method / gateway.

gatewayrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idstring
numberstring
externalReferencestring | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
pdfUrlrequiredstring

Relative URL of the PDF (send your API key).

hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg2t1x2y0009txn0001abcd",
      "object": "receipt",
      "receiptNumber": "CP-20260925-9F3A1C7B",
      "reference": "CP-20260925-9F3A1C7B",
      "status": "complete",
      "amount": 1150,
      "currency": "ZAR",
      "taxAmount": 150,
      "discountAmount": null,
      "refundedAmount": 0,
      "description": "Invoice INV-00042",
      "payerName": "Thandi Nkosi",
      "payerEmail": "[email protected]",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "paymentMethod": "PayFast",
      "gateway": "payfast",
      "invoice": {
        "id": "cmg2i4n5v0004inv0001abcd",
        "number": "INV-00042",
        "externalReference": "ORD-5531"
      },
      "paidAt": "2026-09-25T08:14:03.000Z",
      "createdAt": "2026-09-25T08:12:40.000Z",
      "pdfUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd?format=pdf"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Bad date format or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "from/to must be YYYY-MM-DD"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Get a receipt#

GET/api/v1/receipts/{id}

A receipt by transaction ID or payment reference. Add ?format=pdf to download the branded receipt PDF (application/pdf) instead of JSON. Only completed, partially refunded or refunded payments have receipts.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Transaction ID or payment reference (CP-…).

Query parameters#

Query parameters
FieldTypeDescription
formatstring

pdf returns the PDF.

One of: pdf

Responses#

200The receipt (JSON), or the PDF with `?format=pdf`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring

Transaction ID.

objectrequiredstring

One of: receipt

receiptNumberrequiredstring

The payment reference.

referencerequiredstring
statusrequiredstring

One of: complete, partially_refunded, refunded

amountrequirednumber
currencyrequiredstring
taxAmountrequirednumber | null

Tax included in the payment, when known.

discountAmountrequirednumber | null
refundedAmountrequirednumber
descriptionrequiredstring | null
payerNamerequiredstring | null
payerEmailrequiredstring | null
customerIdrequiredstring | null
paymentMethodrequiredstring

Display name of the payment method / gateway.

gatewayrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idstring
numberstring
externalReferencestring | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
pdfUrlrequiredstring

Relative URL of the PDF (send your API key).

Example
{
  "id": "cmg2t1x2y0009txn0001abcd",
  "object": "receipt",
  "receiptNumber": "CP-20260925-9F3A1C7B",
  "reference": "CP-20260925-9F3A1C7B",
  "status": "complete",
  "amount": 1150,
  "currency": "ZAR",
  "taxAmount": 150,
  "discountAmount": null,
  "refundedAmount": 0,
  "description": "Invoice INV-00042",
  "payerName": "Thandi Nkosi",
  "payerEmail": "[email protected]",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "paymentMethod": "PayFast",
  "gateway": "payfast",
  "invoice": {
    "id": "cmg2i4n5v0004inv0001abcd",
    "number": "INV-00042",
    "externalReference": "ORD-5531"
  },
  "paidAt": "2026-09-25T08:14:03.000Z",
  "createdAt": "2026-09-25T08:12:40.000Z",
  "pdfUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd?format=pdf"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No receipt with this ID or reference (or the payment is not complete).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Receipt not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List refunds#

GET/api/v1/refunds

Refunds, newest first, with keyset pagination.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

Filter by status.

One of: pending, processed, failed

customerIdstring

Filter by customer.

transactionReferencestring

Refunds of the payment with this reference.

fromstring (date)

Start date (YYYY-MM-DD, SAST, inclusive) on the date the refund was recorded.

tostring (date)

End date (YYYY-MM-DD, SAST, inclusive) on the date the refund was recorded.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of refunds.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredRefundRecord[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: refund

refundNumberrequiredstring
amountrequirednumber
currencyrequiredstring
statusrequiredstring

One of: pending, processed, failed

reasonrequiredstring | null
providerRefrequiredstring | null

The gateway's refund ID.

customerIdrequiredstring | null
transactionrequiredobject
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
invoiceIdstring | null
processedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
pdfUrlrequiredstring

Relative URL of the refund note PDF.

hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg4f5e6d0008rfd0001abcd",
      "object": "refund",
      "refundNumber": "REF-7C21A9F0",
      "amount": 200,
      "currency": "ZAR",
      "status": "processed",
      "reason": "Duplicate charge",
      "providerRef": "1234567",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "transaction": {
        "id": "cmg2t1x2y0009txn0001abcd",
        "reference": "CP-20260925-9F3A1C7B",
        "invoiceId": "cmg2i4n5v0004inv0001abcd"
      },
      "processedAt": "2026-09-26T09:00:00.000Z",
      "createdAt": "2026-09-26T08:58:00.000Z",
      "pdfUrl": "/api/v1/refunds/cmg4f5e6d0008rfd0001abcd?format=pdf"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status, bad date format or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of pending, processed, failed"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Get a refund#

GET/api/v1/refunds/{id}

A refund by ID or refund number. ?format=pdf returns the refund note PDF.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Refund ID or refund number (REF-…).

Query parameters#

Query parameters
FieldTypeDescription
formatstring

pdf returns the PDF.

One of: pdf

Responses#

200The refund (JSON), or the refund note PDF with `?format=pdf`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: refund

refundNumberrequiredstring
amountrequirednumber
currencyrequiredstring
statusrequiredstring

One of: pending, processed, failed

reasonrequiredstring | null
providerRefrequiredstring | null

The gateway's refund ID.

customerIdrequiredstring | null
transactionrequiredobject
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
invoiceIdstring | null
processedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
pdfUrlrequiredstring

Relative URL of the refund note PDF.

Example
{
  "id": "cmg4f5e6d0008rfd0001abcd",
  "object": "refund",
  "refundNumber": "REF-7C21A9F0",
  "amount": 200,
  "currency": "ZAR",
  "status": "processed",
  "reason": "Duplicate charge",
  "providerRef": "1234567",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "transaction": {
    "id": "cmg2t1x2y0009txn0001abcd",
    "reference": "CP-20260925-9F3A1C7B",
    "invoiceId": "cmg2i4n5v0004inv0001abcd"
  },
  "processedAt": "2026-09-26T09:00:00.000Z",
  "createdAt": "2026-09-26T08:58:00.000Z",
  "pdfUrl": "/api/v1/refunds/cmg4f5e6d0008rfd0001abcd?format=pdf"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No refund with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Refund not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List payouts#

GET/api/v1/payouts

Newest first, with keyset pagination.

Query parameters#

Query parameters
FieldTypeDescription
statusstring

One of: scheduled, submitted, paid, failed, cancelled

kindstring

One of: creditor, salary, refund

customerIdstring
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of payouts.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredPayout[]
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: payout

idrequiredstring
referencerequiredstring

Account reference in the Netcash batch, e.g. PAY-000031.

kindrequiredstring

One of: creditor, salary, refund

statusrequiredstring

One of: scheduled, submitted, paid, failed, cancelled

beneficiaryNamerequiredstring
beneficiaryEmailrequiredstring | null
bankNamerequiredstring | null
accountLast4requiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
statementRefrequiredstring | null

What the beneficiary sees (max 20).

actionDaterequiredstring (date-time)

UTC midnight of the payment date.

submittedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
failureReasonrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
creditNoterequiredobject | null
Show fields
creditNote fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "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"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Invalid status or kind, or unknown `startingAfter`.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "kind must be one of refund, creditor, salary"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Schedule a payout#

POST/api/v1/payouts

Schedules a creditor, salary or refund payment out of your Netcash account (Netcash Creditor & Salary Payments gateway; ZAR). Bank details are validated, stored encrypted and never returned. Emits payout.scheduled. Always send an Idempotency-Key. No plan feature beyond API access is needed.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
kindrequiredstring

One of: creditor, salary, refund

providerIdstring

Default: first enabled Netcash Creditor & Salary Payments gateway (400 if none).

beneficiaryNamerequiredstring

1–50 chars

beneficiaryEmailstring (email)
bankrequiredBankDetailsInput

Validated like the dashboard, stored encrypted and never returned.

Show fields
bank fields
FieldTypeDescription
accountHolderrequiredstring

1–100 chars

accountNumberrequiredstring

1–30 chars

branchCoderequiredstring

1–10 chars

accountTyperequiredstring

One of: current, savings, transmission

bankNamestring

max 100 chars

amountrequirednumber

> 0 · ≤ 5 000 000

actionDaterequiredstring (date)

YYYY-MM-DD, today or later (SAST).

descriptionstring

max 1000 chars

statementRefstring

Default the beneficiary name.

max 20 chars

customerIdstring
customerExternalReferencestring

max 190 chars

Responses#

201Payout scheduled.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Idempotent-Replayed – `true` when this response is a replay of an earlier request with the same Idempotency-Key.
201 response fields
FieldTypeDescription
objectrequiredstring

One of: payout

idrequiredstring
referencerequiredstring

Account reference in the Netcash batch, e.g. PAY-000031.

kindrequiredstring

One of: creditor, salary, refund

statusrequiredstring

One of: scheduled, submitted, paid, failed, cancelled

beneficiaryNamerequiredstring
beneficiaryEmailrequiredstring | null
bankNamerequiredstring | null
accountLast4requiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
statementRefrequiredstring | null

What the beneficiary sees (max 20).

actionDaterequiredstring (date-time)

UTC midnight of the payment date.

submittedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
failureReasonrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
creditNoterequiredobject | null
Show fields
creditNote fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "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"
}
400Validation failed; invalid bank details; no enabled payout gateway; gateway disabled; salary without a salary service key; action date in the past; customer not found.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "No Netcash Creditor & Salary Payments gateway is enabled"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Get a payout#

GET/api/v1/payouts/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Payout ID or reference.

Responses#

200The payout.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: payout

idrequiredstring
referencerequiredstring

Account reference in the Netcash batch, e.g. PAY-000031.

kindrequiredstring

One of: creditor, salary, refund

statusrequiredstring

One of: scheduled, submitted, paid, failed, cancelled

beneficiaryNamerequiredstring
beneficiaryEmailrequiredstring | null
bankNamerequiredstring | null
accountLast4requiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
statementRefrequiredstring | null

What the beneficiary sees (max 20).

actionDaterequiredstring (date-time)

UTC midnight of the payment date.

submittedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
failureReasonrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
creditNoterequiredobject | null
Show fields
creditNote fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "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"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No payout with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Payout not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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 before it is submitted to Netcash; a credit note's reserved amount is released. Emits payout.cancelled.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Payout ID or reference.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Responses#

200The cancelled payout.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectrequiredstring

One of: payout

idrequiredstring
referencerequiredstring

Account reference in the Netcash batch, e.g. PAY-000031.

kindrequiredstring

One of: creditor, salary, refund

statusrequiredstring

One of: scheduled, submitted, paid, failed, cancelled

beneficiaryNamerequiredstring
beneficiaryEmailrequiredstring | null
bankNamerequiredstring | null
accountLast4requiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
statementRefrequiredstring | null

What the beneficiary sees (max 20).

actionDaterequiredstring (date-time)

UTC midnight of the payment date.

submittedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
failureReasonrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
creditNoterequiredobject | null
Show fields
creditNote fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "object": "payout",
  "id": "cmg3p4q5r0003pay0001abcd",
  "reference": "PAY-000031",
  "kind": "creditor",
  "status": "cancelled",
  "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"
}
400The payout is no longer scheduled.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "A submitted payout cannot be cancelled"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API, or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404No payout with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Payout not found"
}
409The Idempotency-Key was already used with a different request body.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/payouts/cmg3p4q5r0003pay0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

List mandates#

GET/api/v1/mandates

Newest first. Requires Debit orders in your plan.

Query parameters#

Query parameters
FieldTypeDescription
customerIdstring

Filter by customer.

statusstring

Filter by status.

One of: pending, active, paused, cancelled

accountReferencestring

Exact match (case-insensitive), e.g. DO7F3A1C9B2E.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Mandates.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredMandate[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: mandate

accountReferencerequiredstring

DO + 10 hex characters; prefixes the debit order transaction references.

statusrequiredstring

One of: pending, active, paused, cancelled

stagerequiredstring

Human stage: pending mandates are awaiting_signature until authorised, then awaiting_approval when your settings require mandate approval.

One of: awaiting_signature, awaiting_approval, pending, active, paused, cancelled, rejected

customerIdrequiredstring
productIdrequiredstring | null
subscriptionIdrequiredstring | null

Customer subscription the mandate collects.

descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

frequencyrequiredstring

One of: monthly, quarterly, biannually, annually

debitDayrequiredinteger
startDaterequiredstring (date)
endDaterequiredstring (date) | null
nextDebitDaterequiredstring (date) | null
bankrequiredobject
Show fields
bank fields
FieldTypeDescription
namestring | null
branchCodestring
accountTypestring

One of: current, savings, transmission

accountHolderstring
accountNumberLast4string
idNumberLast4requiredstring | null
eMandateUrlrequiredstring | null

Netcash e-mandate URL while waiting for the customer to sign it.

authorisedAtrequiredstring (date-time) | null

When the customer authorised it (signed agreement, e-mandate, or created as offline).

approvedAtrequiredstring (date-time) | null
rejectedAtrequiredstring (date-time) | null
rejectionReasonrequiredstring | null
failureCountrequiredinteger

Consecutive unpaids; 3 pauses the mandate.

lastCollectedAtrequiredstring (date) | null
agreementobject

Online agreement state (latest of the last 5 agreements).

Show fields
agreement fields
FieldTypeDescription
signedboolean
signedAtstring (date-time) | null
latestobject | null
Show fields
latest fields
FieldTypeDescription
idstring
statusstring

One of: open, signed, cancelled, expired

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "data": [
    {
      "id": "cmg4m3n4o0006mdt0001abcd",
      "object": "mandate",
      "accountReference": "DO7F3A1C9B2E",
      "status": "pending",
      "stage": "awaiting_signature",
      "customerId": "cmg2c0s7t0003cust0001abcd",
      "productId": null,
      "subscriptionId": null,
      "description": "Monthly service fee",
      "amount": 499,
      "currency": "ZAR",
      "frequency": "monthly",
      "debitDay": 1,
      "startDate": "2026-10-01",
      "endDate": null,
      "nextDebitDate": null,
      "bank": {
        "name": "FNB",
        "branchCode": "250655",
        "accountType": "current",
        "accountHolder": "T Nkosi",
        "accountNumberLast4": "6789"
      },
      "idNumberLast4": null,
      "eMandateUrl": null,
      "authorisedAt": null,
      "approvedAt": null,
      "rejectedAt": null,
      "rejectionReason": null,
      "failureCount": 0,
      "lastCollectedAt": null,
      "agreement": {
        "signed": false,
        "signedAt": null,
        "latest": {
          "id": "cmg4a7g8r0007agr0001abcd",
          "status": "open"
        }
      },
      "createdAt": "2026-09-28T08:20:00.000Z",
      "updatedAt": "2026-09-28T08:20:00.000Z"
    }
  ]
}
400Invalid status.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of pending, active, paused, cancelled"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Create a mandate#

POST/api/v1/mandates

Creates a debit order mandate (201). Bank details are validated. The mandate stays pending until authorised (and approved, when your debit order settings require mandate approval). With authority: "agreement" (default) the customer is emailed an agreement to sign online; the signing URL is not returned here. Use POST /api/v1/mandates/{id}/agreement with {"email": false} to get one. Counts towards your plan's mandate limit. Requires Debit orders.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
customerIdstring
customerobject | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
providerIdstring

Netcash provider; default your first enabled Netcash provider.

productIdstring
subscriptionIdstring

Customer subscription to collect. Not one your platform bills (collectionMethod: external): 409 external_subscription.

descriptionstring

max 500 chars

bankrequiredobject
Show fields
bank fields
FieldTypeDescription
namestring

max 60 chars

branchCoderequiredstring
accountNumberrequiredstring

Validated (check digits) for live providers.

accountTypestring

One of: current, savings, transmission

default "current"

accountHolderrequiredstring

2–30 chars

idNumberstring

max 20 chars

amountrequirednumber

> 0 · ≤ 1 000 000

frequencystring

One of: monthly, quarterly, biannually, annually

default "monthly"

debitDayinteger

Default: your debit order settings' default debit day.

≥ 1 · ≤ 31

startDatestring (date)

YYYY-MM-DD, today or later (default today).

endDatestring (date)

After startDate.

notesstring

max 2000 chars

authoritystring

agreement: CentraPoint emails its debit order agreement for online signing. emandate: a Netcash e-mandate. offline: you hold a signed mandate (requires confirmOfflineMandate: true; active at once unless mandate approval is required).

One of: agreement, emandate, offline

default "agreement"

confirmOfflineMandateboolean

Responses#

201The new mandate.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: mandate

accountReferencerequiredstring

DO + 10 hex characters; prefixes the debit order transaction references.

statusrequiredstring

One of: pending, active, paused, cancelled

stagerequiredstring

Human stage: pending mandates are awaiting_signature until authorised, then awaiting_approval when your settings require mandate approval.

One of: awaiting_signature, awaiting_approval, pending, active, paused, cancelled, rejected

customerIdrequiredstring
productIdrequiredstring | null
subscriptionIdrequiredstring | null

Customer subscription the mandate collects.

descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

frequencyrequiredstring

One of: monthly, quarterly, biannually, annually

debitDayrequiredinteger
startDaterequiredstring (date)
endDaterequiredstring (date) | null
nextDebitDaterequiredstring (date) | null
bankrequiredobject
Show fields
bank fields
FieldTypeDescription
namestring | null
branchCodestring
accountTypestring

One of: current, savings, transmission

accountHolderstring
accountNumberLast4string
idNumberLast4requiredstring | null
eMandateUrlrequiredstring | null

Netcash e-mandate URL while waiting for the customer to sign it.

authorisedAtrequiredstring (date-time) | null

When the customer authorised it (signed agreement, e-mandate, or created as offline).

approvedAtrequiredstring (date-time) | null
rejectedAtrequiredstring (date-time) | null
rejectionReasonrequiredstring | null
failureCountrequiredinteger

Consecutive unpaids; 3 pauses the mandate.

lastCollectedAtrequiredstring (date) | null
agreementobject

Online agreement state (latest of the last 5 agreements).

Show fields
agreement fields
FieldTypeDescription
signedboolean
signedAtstring (date-time) | null
latestobject | null
Show fields
latest fields
FieldTypeDescription
idstring
statusstring

One of: open, signed, cancelled, expired

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
warningsrequiredstring[]

Non-blocking bank account validation warnings.

agreementSentobject

With authority: "agreement": the agreement issued for online signing.

Show fields
agreementSent fields
FieldTypeDescription
idstring
emailedboolean
expiresAtstring (date-time)
Example
{
  "id": "cmg4m3n4o0006mdt0001abcd",
  "object": "mandate",
  "accountReference": "DO7F3A1C9B2E",
  "status": "pending",
  "stage": "awaiting_signature",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "productId": null,
  "subscriptionId": null,
  "description": "Monthly service fee",
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "debitDay": 1,
  "startDate": "2026-10-01",
  "endDate": null,
  "nextDebitDate": null,
  "bank": {
    "name": "FNB",
    "branchCode": "250655",
    "accountType": "current",
    "accountHolder": "T Nkosi",
    "accountNumberLast4": "6789"
  },
  "idNumberLast4": null,
  "eMandateUrl": null,
  "authorisedAt": null,
  "approvedAt": null,
  "rejectedAt": null,
  "rejectionReason": null,
  "failureCount": 0,
  "lastCollectedAt": null,
  "agreement": {
    "signed": false,
    "signedAt": null,
    "latest": {
      "id": "cmg4a7g8r0007agr0001abcd",
      "status": "open"
    }
  },
  "createdAt": "2026-09-28T08:20:00.000Z",
  "updatedAt": "2026-09-28T08:20:00.000Z",
  "warnings": [],
  "agreementSent": {
    "id": "cmg4a7g8r0007agr0001abcd",
    "emailed": true,
    "expiresAt": "2026-10-12T08:20:00.000Z"
  }
}
400Validation failed: bank details, start date in the past, no Netcash provider, offline without confirmOfflineMandate, etc.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Branch code must be 6 digits and account number 5-20 digits"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Debit orders not in your plan, mandate limit reached (`plan_limit`), or account read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_limit",
  "message": "Active debit order mandates limit reached (50/50) on the Business plan. Upgrade under Settings > Billing."
}
409`idempotency_conflict`: Idempotency-Key reused with a different body. `external_subscription`: `subscriptionId` is a subscription your platform bills (`collectionMethod: external`), which CentraPoint never collects.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
idempotencyConflict
{
  "error": "idempotency_conflict",
  "message": "This Idempotency-Key was already used with a different request body"
}
externalSubscription
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot collect it with a debit order. Create the mandate without subscriptionId."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/mandates" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalReference": "CRM-1001"
    },
    "description": "Monthly service fee",
    "bank": {
      "name": "FNB",
      "branchCode": "250655",
      "accountNumber": "62123456789",
      "accountType": "current",
      "accountHolder": "T Nkosi"
    },
    "amount": 499,
    "frequency": "monthly",
    "debitDay": 1,
    "startDate": "2026-10-01"
  }'

Get a mandate#

GET/api/v1/mandates/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The mandate.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: mandate

accountReferencerequiredstring

DO + 10 hex characters; prefixes the debit order transaction references.

statusrequiredstring

One of: pending, active, paused, cancelled

stagerequiredstring

Human stage: pending mandates are awaiting_signature until authorised, then awaiting_approval when your settings require mandate approval.

One of: awaiting_signature, awaiting_approval, pending, active, paused, cancelled, rejected

customerIdrequiredstring
productIdrequiredstring | null
subscriptionIdrequiredstring | null

Customer subscription the mandate collects.

descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

frequencyrequiredstring

One of: monthly, quarterly, biannually, annually

debitDayrequiredinteger
startDaterequiredstring (date)
endDaterequiredstring (date) | null
nextDebitDaterequiredstring (date) | null
bankrequiredobject
Show fields
bank fields
FieldTypeDescription
namestring | null
branchCodestring
accountTypestring

One of: current, savings, transmission

accountHolderstring
accountNumberLast4string
idNumberLast4requiredstring | null
eMandateUrlrequiredstring | null

Netcash e-mandate URL while waiting for the customer to sign it.

authorisedAtrequiredstring (date-time) | null

When the customer authorised it (signed agreement, e-mandate, or created as offline).

approvedAtrequiredstring (date-time) | null
rejectedAtrequiredstring (date-time) | null
rejectionReasonrequiredstring | null
failureCountrequiredinteger

Consecutive unpaids; 3 pauses the mandate.

lastCollectedAtrequiredstring (date) | null
agreementobject

Online agreement state (latest of the last 5 agreements).

Show fields
agreement fields
FieldTypeDescription
signedboolean
signedAtstring (date-time) | null
latestobject | null
Show fields
latest fields
FieldTypeDescription
idstring
statusstring

One of: open, signed, cancelled, expired

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4m3n4o0006mdt0001abcd",
  "object": "mandate",
  "accountReference": "DO7F3A1C9B2E",
  "status": "pending",
  "stage": "awaiting_signature",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "productId": null,
  "subscriptionId": null,
  "description": "Monthly service fee",
  "amount": 499,
  "currency": "ZAR",
  "frequency": "monthly",
  "debitDay": 1,
  "startDate": "2026-10-01",
  "endDate": null,
  "nextDebitDate": null,
  "bank": {
    "name": "FNB",
    "branchCode": "250655",
    "accountType": "current",
    "accountHolder": "T Nkosi",
    "accountNumberLast4": "6789"
  },
  "idNumberLast4": null,
  "eMandateUrl": null,
  "authorisedAt": null,
  "approvedAt": null,
  "rejectedAt": null,
  "rejectionReason": null,
  "failureCount": 0,
  "lastCollectedAt": null,
  "agreement": {
    "signed": false,
    "signedAt": null,
    "latest": {
      "id": "cmg4a7g8r0007agr0001abcd",
      "status": "open"
    }
  },
  "createdAt": "2026-09-28T08:20:00.000Z",
  "updatedAt": "2026-09-28T08:20:00.000Z"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403No API access, or the plan feature is missing.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No mandate with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Mandate not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Update a mandate#

PATCH/api/v1/mandates/{id}

Changes the amount and/or debit day, or pauses, resumes or cancels the mandate. Pending mandates can't be set active (they activate once authorised and approved). Idempotency-Key is not used.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountnumber

> 0 · ≤ 1 000 000

debitDayinteger

≥ 1 · ≤ 31

statusstring

paused stops debits, active resumes a paused mandate, cancelled is permanent.

One of: active, paused, cancelled

Responses#

200The updated mandate.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: mandate

accountReferencerequiredstring

DO + 10 hex characters; prefixes the debit order transaction references.

statusrequiredstring

One of: pending, active, paused, cancelled

stagerequiredstring

Human stage: pending mandates are awaiting_signature until authorised, then awaiting_approval when your settings require mandate approval.

One of: awaiting_signature, awaiting_approval, pending, active, paused, cancelled, rejected

customerIdrequiredstring
productIdrequiredstring | null
subscriptionIdrequiredstring | null

Customer subscription the mandate collects.

descriptionrequiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

frequencyrequiredstring

One of: monthly, quarterly, biannually, annually

debitDayrequiredinteger
startDaterequiredstring (date)
endDaterequiredstring (date) | null
nextDebitDaterequiredstring (date) | null
bankrequiredobject
Show fields
bank fields
FieldTypeDescription
namestring | null
branchCodestring
accountTypestring

One of: current, savings, transmission

accountHolderstring
accountNumberLast4string
idNumberLast4requiredstring | null
eMandateUrlrequiredstring | null

Netcash e-mandate URL while waiting for the customer to sign it.

authorisedAtrequiredstring (date-time) | null

When the customer authorised it (signed agreement, e-mandate, or created as offline).

approvedAtrequiredstring (date-time) | null
rejectedAtrequiredstring (date-time) | null
rejectionReasonrequiredstring | null
failureCountrequiredinteger

Consecutive unpaids; 3 pauses the mandate.

lastCollectedAtrequiredstring (date) | null
agreementobject

Online agreement state (latest of the last 5 agreements).

Show fields
agreement fields
FieldTypeDescription
signedboolean
signedAtstring (date-time) | null
latestobject | null
Show fields
latest fields
FieldTypeDescription
idstring
statusstring

One of: open, signed, cancelled, expired

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example
{
  "id": "cmg4m3n4o0006mdt0001abcd",
  "object": "mandate",
  "accountReference": "DO7F3A1C9B2E",
  "status": "pending",
  "stage": "awaiting_signature",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "productId": null,
  "subscriptionId": null,
  "description": "Monthly service fee",
  "amount": 549,
  "currency": "ZAR",
  "frequency": "monthly",
  "debitDay": 1,
  "startDate": "2026-10-01",
  "endDate": null,
  "nextDebitDate": null,
  "bank": {
    "name": "FNB",
    "branchCode": "250655",
    "accountType": "current",
    "accountHolder": "T Nkosi",
    "accountNumberLast4": "6789"
  },
  "idNumberLast4": null,
  "eMandateUrl": null,
  "authorisedAt": null,
  "approvedAt": null,
  "rejectedAt": null,
  "rejectionReason": null,
  "failureCount": 0,
  "lastCollectedAt": null,
  "agreement": {
    "signed": false,
    "signedAt": null,
    "latest": {
      "id": "cmg4a7g8r0007agr0001abcd",
      "status": "open"
    }
  },
  "createdAt": "2026-09-28T08:20:00.000Z",
  "updatedAt": "2026-09-28T08:20:00.000Z"
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Send amount, debitDay and/or status"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Debit orders not in your plan, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No mandate with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Mandate not found"
}
409`status: "active"` for a mandate that is not paused.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Only paused mandates can be resumed; pending mandates activate once authorised (and approved)"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/mandates/cmg4m3n4o0006mdt0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 549
  }'

Issue a mandate agreement#

POST/api/v1/mandates/{id}/agreement

Issues a new debit order agreement for online signing (any open one is withdrawn) and returns its signing URL, valid for 14 days. Emails it to the customer unless email: false. Not idempotent: the response carries a signing token and is never stored for replay.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json

Request body fields
FieldTypeDescription
emailboolean

false: don't email it, only return signUrl (e.g. to show in your own flow).

default true

notesstring

max 2000 chars

Responses#

201The agreement.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: mandate_agreement

mandateIdrequiredstring
statusrequiredstring

pending for a new agreement.

signUrlrequiredstring

Public signing page. Treat it as a secret; valid until expiresAt (14 days).

expiresAtrequiredstring (date-time)
emailedrequiredboolean
Example
{
  "id": "cmg4a7g8r0007agr0001abcd",
  "object": "mandate_agreement",
  "mandateId": "cmg4m3n4o0006mdt0001abcd",
  "status": "pending",
  "signUrl": "https://app.centrapoint.co.za/sign-mandate/3q9…",
  "expiresAt": "2026-10-12T08:20:00.000Z",
  "emailed": false
}
400Validation failed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "Invalid body"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Debit orders not in your plan, or the account is read-only.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "account_restricted",
  "message": "Your free trial has ended. Choose a plan to continue."
}
404No mandate with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Mandate not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/mandates/cmg4m3n4o0006mdt0001abcd/agreement" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": false
  }'

List reconciliation runs#

GET/api/v1/reconciliation/runs

Statement imports (Netcash statements per Netcash account and CSV uploads) with their results, newest first by start time. Requires the Reconciliation feature (Business plan and above).

Query parameters#

Query parameters
FieldTypeDescription
fromstring (date)

YYYY-MM-DD (South African time): runs started on or after this day.

tostring (date)

YYYY-MM-DD (South African time): runs started on or before this day.

accountstring

Only runs of this Netcash account (acct_…, see List Netcash accounts).

sourcestring

netcash_statement or csv_upload.

One of: netcash_statement, csv_upload

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

Responses#

200Runs.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredReconciliationRun[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
sourcerequiredstring

One of: netcash_statement, csv_upload

accountrequirednull | ReconciliationRunAccount

Netcash statement runs: the account and its gateways. Null for CSV imports.

Show fields
account fields
FieldTypeDescription
idrequiredstring | null

Stable account id, one per service key (the key itself is never returned). Null for runs from before accounts.

providersrequiredReconciliationProvider[]

Gateways sharing the account when the run was created.

Show fields
providers fields
FieldTypeDescription
idrequiredstring

Payment gateway (provider) ID.

namerequiredstring
typerequiredstring

netcash, netcash_paynow or netcash_creditor. A gateway still set up with the retired Netcash Recurring Card module shows netcash_recurring until it is converted to netcash_paynow.

statementDaterequiredstring (date-time) | null

End of the statement period (or its start when no end is known).

periodStartrequiredstring (date-time) | null
periodEndrequiredstring (date-time) | null
statusrequiredstring

balanced: nothing needs attention; exceptions: at least one item does.

One of: processing, failed, balanced, exceptions

lineCountrequiredinteger

Statement lines imported.

matchedrequiredinteger

Lines matched to a CentraPoint payment or payout.

unmatchedrequiredinteger

Lines no payment or payout could be found for.

notReceivedrequiredinteger

Number of not_received and not_debited items.

exceptionsrequiredinteger

Items needing attention (mismatches, unmatched lines and not_received / not_debited items).

totalsrequiredReconciliationTotals

Positive sums of the statement lines in each category. Settlements, unlinked fees and balance lines are counted here but are not items.

Show fields
totals fields
FieldTypeDescription
receiptsrequirednumber

Collections.

feesrequirednumber
refundsrequirednumber
payoutsrequirednumber

Transfers to your own bank account (same as settlements).

settlementsrequirednumber

Transfers to your own bank account.

disbursementsrequirednumber

Creditor, salary and refund payouts, net of returns.

unpaidsrequirednumber

Returned debit orders, reversals, chargebacks and declines.

openingBalancerequirednumber | null

From the statement's opening balance line, if present.

closingBalancerequirednumber | null

From the statement's closing balance line, if present.

balancerequiredReconciliationBalance

Signed balance view: money in positive, money out negative.

Show fields
balance fields
FieldTypeDescription
openingrequirednumber | null

Opening balance line of the statement, when present.

collectionsrequirednumber
unpaidsrequirednumber
refundsrequirednumber
feesrequirednumber
disbursementsrequirednumber

Creditor, salary and refund payouts.

settlementsrequirednumber

Transfers to your own bank account.

otherrequirednumber
closingrequirednumber | null

Closing balance line of the statement, when present.

computedClosingrequirednumber | null

Opening balance plus every line.

differencerequirednumber | null

closing minus computedClosing; non-zero means lines are missing.

triggerrequiredstring | null

cron (nightly import, also when Netcash signals the requested statement), postback (a statement fetched from Netcash to confirm one posted to the Statement postback URL, for example one requested by other software using the same Account service key), manual (Run now or a CSV import) or admin (started by CentraPoint on your behalf). Null for runs from before this field.

One of: cron, manual, admin, null

errorrequiredstring | null
createdAtrequiredstring (date-time)
completedAtrequiredstring (date-time) | null
Example
{
  "data": [
    {
      "id": "cmg3r7c0n0013run0001abcd",
      "source": "netcash_statement",
      "account": {
        "id": "acct_3f9a1c7b20d4e5f6",
        "providers": [
          {
            "id": "cmg3prov0000paynow000001",
            "name": "Card payments",
            "type": "netcash_paynow"
          },
          {
            "id": "cmg3prov0000recur0000002",
            "name": "Subscriptions",
            "type": "netcash_paynow"
          },
          {
            "id": "cmg3prov0000credit000003",
            "name": "Payouts",
            "type": "netcash_creditor"
          }
        ]
      },
      "statementDate": "2026-09-24T22:00:00.000Z",
      "periodStart": "2026-09-23T22:00:00.000Z",
      "periodEnd": "2026-09-24T22:00:00.000Z",
      "status": "exceptions",
      "lineCount": 42,
      "matched": 38,
      "unmatched": 1,
      "notReceived": 1,
      "exceptions": 2,
      "totals": {
        "receipts": 48250.5,
        "fees": 612.4,
        "refunds": 499,
        "payouts": 33000,
        "settlements": 33000,
        "disbursements": 12000,
        "unpaids": 350
      },
      "openingBalance": 1203.55,
      "closingBalance": 2992.65,
      "balance": {
        "opening": 1203.55,
        "collections": 48250.5,
        "unpaids": -350,
        "refunds": -499,
        "fees": -612.4,
        "disbursements": -12000,
        "settlements": -33000,
        "other": 0,
        "closing": 2992.65,
        "computedClosing": 2992.65,
        "difference": 0
      },
      "trigger": "cron",
      "error": null,
      "createdAt": "2026-09-25T02:00:03.000Z",
      "completedAt": "2026-09-25T02:04:11.000Z"
    }
  ]
}
400Bad date or unknown source.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "from and to must be YYYY-MM-DD"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or reconciliation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No Netcash account with this `account` id in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Account not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/runs?account=acct_3f9a1c7b20d4e5f6" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a reconciliation run#

GET/api/v1/reconciliation/runs/{id}

The run summary plus its items: every statement line except ignored ones (account fees, settlements and balances are only in totals and balance; fees linked to a payment are included), and for completed Netcash statement runs, not_received and not_debited items.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200The run with items.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
sourcerequiredstring

One of: netcash_statement, csv_upload

accountrequirednull | ReconciliationRunAccount

Netcash statement runs: the account and its gateways. Null for CSV imports.

Show fields
account fields
FieldTypeDescription
idrequiredstring | null

Stable account id, one per service key (the key itself is never returned). Null for runs from before accounts.

providersrequiredReconciliationProvider[]

Gateways sharing the account when the run was created.

Show fields
providers fields
FieldTypeDescription
idrequiredstring

Payment gateway (provider) ID.

namerequiredstring
typerequiredstring

netcash, netcash_paynow or netcash_creditor. A gateway still set up with the retired Netcash Recurring Card module shows netcash_recurring until it is converted to netcash_paynow.

statementDaterequiredstring (date-time) | null

End of the statement period (or its start when no end is known).

periodStartrequiredstring (date-time) | null
periodEndrequiredstring (date-time) | null
statusrequiredstring

balanced: nothing needs attention; exceptions: at least one item does.

One of: processing, failed, balanced, exceptions

lineCountrequiredinteger

Statement lines imported.

matchedrequiredinteger

Lines matched to a CentraPoint payment or payout.

unmatchedrequiredinteger

Lines no payment or payout could be found for.

notReceivedrequiredinteger

Number of not_received and not_debited items.

exceptionsrequiredinteger

Items needing attention (mismatches, unmatched lines and not_received / not_debited items).

totalsrequiredReconciliationTotals

Positive sums of the statement lines in each category. Settlements, unlinked fees and balance lines are counted here but are not items.

Show fields
totals fields
FieldTypeDescription
receiptsrequirednumber

Collections.

feesrequirednumber
refundsrequirednumber
payoutsrequirednumber

Transfers to your own bank account (same as settlements).

settlementsrequirednumber

Transfers to your own bank account.

disbursementsrequirednumber

Creditor, salary and refund payouts, net of returns.

unpaidsrequirednumber

Returned debit orders, reversals, chargebacks and declines.

openingBalancerequirednumber | null

From the statement's opening balance line, if present.

closingBalancerequirednumber | null

From the statement's closing balance line, if present.

balancerequiredReconciliationBalance

Signed balance view: money in positive, money out negative.

Show fields
balance fields
FieldTypeDescription
openingrequirednumber | null

Opening balance line of the statement, when present.

collectionsrequirednumber
unpaidsrequirednumber
refundsrequirednumber
feesrequirednumber
disbursementsrequirednumber

Creditor, salary and refund payouts.

settlementsrequirednumber

Transfers to your own bank account.

otherrequirednumber
closingrequirednumber | null

Closing balance line of the statement, when present.

computedClosingrequirednumber | null

Opening balance plus every line.

differencerequirednumber | null

closing minus computedClosing; non-zero means lines are missing.

triggerrequiredstring | null

cron (nightly import, also when Netcash signals the requested statement), postback (a statement fetched from Netcash to confirm one posted to the Statement postback URL, for example one requested by other software using the same Account service key), manual (Run now or a CSV import) or admin (started by CentraPoint on your behalf). Null for runs from before this field.

One of: cron, manual, admin, null

errorrequiredstring | null
createdAtrequiredstring (date-time)
completedAtrequiredstring (date-time) | null
itemsrequiredReconciliationItem[]
Show fields
items fields
FieldTypeDescription
idrequiredstring | null

Statement line ID (null for not_received / not_debited items).

runIdstring

Run the statement line belongs to (not on not_received / not_debited items).

statusrequiredstring

One of: matched, amount_mismatch, exception, unmatched_receipt, unmatched_debit, not_received, not_debited

matchStatusstring

Raw line status (not on not_received / not_debited items).

One of: matched, unmatched, exception, ignored

categoryrequiredstring

One of: collection, unpaid, refund, fee, disbursement, payout, other

kindrequiredstring | null

How the line was resolved.

One of: collection, renewal, duplicate_collection, fee, refund, chargeback, reversal, decline, unpaid, payout_paid, payout_returned, settlement, balance, offline_payment, manual, null

codestring | null

Netcash transaction type code (or the CSV code column). Not on not_received / not_debited items.

referencerequiredstring | null

CentraPoint payment (or payout) reference when matched, else the reference on the statement line.

externalReferencerequiredstring | null

From the payment link or EFT order of the matched payment.

transactionIdrequiredstring | null

The matched payment.

payoutIdrequiredstring | null

The matched payout.

payoutReferencerequiredstring | null

The matched payout's reference (PAY-…).

expectedAmountrequirednumber | null

The CentraPoint payment amount (payouts: negative payout amount).

statementAmountrequirednumber | null

Signed: + money in, − money out. Null for not_received / not_debited.

daterequiredstring (date-time) | null

Statement line date (not_debited: the payout's action date).

descriptionrequiredstring | null
noterequiredstring | null

Why the item has this status.

Example
{
  "id": "cmg3r7c0n0013run0001abcd",
  "source": "netcash_statement",
  "account": {
    "id": "acct_3f9a1c7b20d4e5f6",
    "providers": [
      {
        "id": "cmg3prov0000paynow000001",
        "name": "Card payments",
        "type": "netcash_paynow"
      },
      {
        "id": "cmg3prov0000recur0000002",
        "name": "Subscriptions",
        "type": "netcash_paynow"
      },
      {
        "id": "cmg3prov0000credit000003",
        "name": "Payouts",
        "type": "netcash_creditor"
      }
    ]
  },
  "statementDate": "2026-09-24T22:00:00.000Z",
  "periodStart": "2026-09-23T22:00:00.000Z",
  "periodEnd": "2026-09-24T22:00:00.000Z",
  "status": "exceptions",
  "lineCount": 42,
  "matched": 38,
  "unmatched": 1,
  "notReceived": 1,
  "exceptions": 2,
  "totals": {
    "receipts": 48250.5,
    "fees": 612.4,
    "refunds": 499,
    "payouts": 33000,
    "settlements": 33000,
    "disbursements": 12000,
    "unpaids": 350
  },
  "openingBalance": 1203.55,
  "closingBalance": 2992.65,
  "balance": {
    "opening": 1203.55,
    "collections": 48250.5,
    "unpaids": -350,
    "refunds": -499,
    "fees": -612.4,
    "disbursements": -12000,
    "settlements": -33000,
    "other": 0,
    "closing": 2992.65,
    "computedClosing": 2992.65,
    "difference": 0
  },
  "trigger": "cron",
  "error": null,
  "createdAt": "2026-09-25T02:00:03.000Z",
  "completedAt": "2026-09-25T02:04:11.000Z",
  "items": [
    {
      "id": "cmg3line000000000000001",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "matched",
      "matchStatus": "matched",
      "category": "collection",
      "kind": "collection",
      "code": "PNC",
      "reference": "CP-20260924-9F3A1C7B",
      "externalReference": "ORDER-1001",
      "transactionId": "cmg3tx00000000000000001",
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": 499,
      "statementAmount": 499,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Pay Now card CP-20260924-9F3A1C7B",
      "note": "Confirmed by statement"
    },
    {
      "id": "cmg3line000000000000002",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "matched",
      "matchStatus": "matched",
      "category": "fee",
      "kind": "fee",
      "code": "NSF",
      "reference": "CP-20260924-9F3A1C7B",
      "externalReference": null,
      "transactionId": "cmg3tx00000000000000001",
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": 499,
      "statementAmount": -14.97,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Pay Now fee CP-20260924-9F3A1C7B",
      "note": "Fee 14.97 recorded on CP-20260924-9F3A1C7B"
    },
    {
      "id": "cmg3line000000000000003",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "amount_mismatch",
      "matchStatus": "exception",
      "category": "collection",
      "kind": "collection",
      "code": "PNC",
      "reference": "CP-20260924-41D07E2A",
      "externalReference": "ORDER-1002",
      "transactionId": "cmg3tx00000000000000002",
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": 1200,
      "statementAmount": 1100,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Pay Now card CP-20260924-41D07E2A",
      "note": "Amount differs: statement 1100.00 vs transaction 1200.00"
    },
    {
      "id": "cmg3line000000000000004",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "matched",
      "matchStatus": "matched",
      "category": "disbursement",
      "kind": "payout_paid",
      "code": "CRP",
      "reference": "PAY-000042",
      "externalReference": null,
      "transactionId": null,
      "payoutId": "cmg3payout0000000000042",
      "payoutReference": "PAY-000042",
      "expectedAmount": -1500,
      "statementAmount": -1500,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Creditor payment | PAY-000042",
      "note": "Payout PAY-000042 debited - marked paid"
    },
    {
      "id": "cmg3line000000000000005",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "unmatched_receipt",
      "matchStatus": "unmatched",
      "category": "collection",
      "kind": null,
      "code": "PNE",
      "reference": null,
      "externalReference": null,
      "transactionId": null,
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": null,
      "statementAmount": 75,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Pay Now EFT",
      "note": "Money received with no CentraPoint payment"
    },
    {
      "id": null,
      "status": "not_received",
      "category": "collection",
      "kind": null,
      "reference": "CP-20260920-7C21A9F0",
      "externalReference": "ORDER-0990",
      "transactionId": "cmg3tx00000000000000003",
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": 250,
      "statementAmount": null,
      "date": null,
      "description": "Website hosting",
      "note": "Completed in CentraPoint but not on the statement after 3 days"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or reconciliation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No run with this ID in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Reconciliation run not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List statement lines#

GET/api/v1/reconciliation/lines

Statement lines across runs, newest line date first, with keyset pagination. Requires the Reconciliation feature (Business plan and above).

Query parameters#

Query parameters
FieldTypeDescription
statusstring

open (unmatched and exceptions), matched, unmatched, exception or ignored (raw line status).

One of: open, matched, unmatched, exception, ignored

categorystring

Line category.

One of: collection, unpaid, refund, fee, disbursement, payout, other

accountstring

Only lines of this Netcash account (acct_…).

runIdstring

Only lines of this run.

fromstring (date)

Start date (YYYY-MM-DD, SAST, inclusive) on the statement line date.

tostring (date)

End date (YYYY-MM-DD, SAST, inclusive) on the statement line date.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200A page of statement lines.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredReconciliationLine[]
Show fields
data fields
FieldTypeDescription
idrequiredstring

Statement line ID.

runIdrequiredstring
statusrequiredstring

Item status of the line; ignored for information, balance, settlement and unlinked fee lines.

One of: matched, amount_mismatch, exception, unmatched_receipt, unmatched_debit, ignored

matchStatusrequiredstring

Raw line status.

One of: matched, unmatched, exception, ignored

categoryrequiredstring

One of: collection, unpaid, refund, fee, disbursement, payout, other

kindrequiredstring | null

How the line was resolved.

One of: collection, renewal, duplicate_collection, fee, refund, chargeback, reversal, decline, unpaid, payout_paid, payout_returned, settlement, balance, offline_payment, manual, null

coderequiredstring | null

Netcash transaction type code (or the CSV code column).

referencerequiredstring | null

CentraPoint payment (or payout) reference when matched, else the reference on the statement line.

externalReferencerequiredstring | null

From the payment link or EFT order of the matched payment.

transactionIdrequiredstring | null

The matched payment.

payoutIdrequiredstring | null

The matched payout.

payoutReferencerequiredstring | null

The matched payout's reference (PAY-…).

expectedAmountrequirednumber | null

The CentraPoint payment amount (payouts: negative payout amount).

statementAmountrequirednumber

Signed: + money in, − money out.

daterequiredstring (date-time)

Statement line date.

descriptionrequiredstring | null
noterequiredstring | null

Why the item has this status.

hasMorerequiredboolean

More items exist after this page.

nextCursorrequiredstring | null

Pass as startingAfter to get the next page; null on the last page.

Example
{
  "data": [
    {
      "id": "cmg3line000000000000005",
      "runId": "cmg3r7c0n0013run0001abcd",
      "status": "unmatched_receipt",
      "matchStatus": "unmatched",
      "category": "collection",
      "kind": null,
      "code": "PNE",
      "reference": null,
      "externalReference": null,
      "transactionId": null,
      "payoutId": null,
      "payoutReference": null,
      "expectedAmount": null,
      "statementAmount": 75,
      "date": "2026-09-24T00:00:00.000Z",
      "description": "Pay Now EFT",
      "note": "Money received with no CentraPoint payment"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
400Unknown status or category, bad date, or an invalid cursor.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invalid_request",
  "message": "status must be one of open, matched, unmatched, exception, ignored"
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or reconciliation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
404No Netcash account with this `account` id in your organisation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Account not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/lines?account=acct_3f9a1c7b20d4e5f6" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List Netcash accounts#

GET/api/v1/reconciliation/accounts

Your Netcash accounts (Netcash gateways grouped by Account service key) with the last run, open items and a 30-day balance view. Requires the Reconciliation feature (Business plan and above).

Responses#

200Accounts.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredReconciliationAccount[]
Show fields
data fields
FieldTypeDescription
idrequiredstring

Stable account id, one per service key (the key itself is never returned).

objectrequiredstring

One of: reconciliation_account

providersrequiredReconciliationProvider[]
Show fields
providers fields
FieldTypeDescription
idrequiredstring

Payment gateway (provider) ID.

namerequiredstring
typerequiredstring

netcash, netcash_paynow or netcash_creditor. A gateway still set up with the retired Netcash Recurring Card module shows netcash_recurring until it is converted to netcash_paynow.

lastRunrequirednull | object
Show fields
lastRun fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

processing (statement requested or importing), completed or failed.

startedAtrequiredstring (date-time)
finishedAtrequiredstring (date-time) | null
errorrequiredstring | null
lastStatementrequirednull | object
Show fields
lastStatement fields
FieldTypeDescription
runIdrequiredstring
periodStartrequiredstring (date-time) | null
periodEndrequiredstring (date-time) | null
unmatchedrequiredinteger

Open unmatched lines of the account.

unmatchedAmountrequirednumber

Signed sum of the open unmatched lines.

exceptionsrequiredinteger

Open exception lines of the account.

notReceivedrequiredinteger

not_received / not_debited items of the latest completed run.

balancerequiredobject
Show fields
balance fields
FieldTypeDescription
openingrequirednumber | null

Opening balance line of the statement, when present.

collectionsrequirednumber
unpaidsrequirednumber
refundsrequirednumber
feesrequirednumber
disbursementsrequirednumber

Creditor, salary and refund payouts.

settlementsrequirednumber

Transfers to your own bank account.

otherrequirednumber
closingrequirednumber | null

Closing balance line of the statement, when present.

computedClosingrequirednumber | null

Opening balance plus every line.

differencerequirednumber | null

closing minus computedClosing; non-zero means lines are missing.

periodDaysrequiredinteger

Days covered (30): statement lines dated in the last 30 days.

Example
{
  "data": [
    {
      "id": "acct_3f9a1c7b20d4e5f6",
      "object": "reconciliation_account",
      "providers": [
        {
          "id": "cmg3prov0000paynow000001",
          "name": "Card payments",
          "type": "netcash_paynow"
        },
        {
          "id": "cmg3prov0000recur0000002",
          "name": "Subscriptions",
          "type": "netcash_paynow"
        },
        {
          "id": "cmg3prov0000credit000003",
          "name": "Payouts",
          "type": "netcash_creditor"
        }
      ],
      "lastRun": {
        "id": "cmg3r7c0n0013run0001abcd",
        "status": "completed",
        "startedAt": "2026-09-25T02:00:03.000Z",
        "finishedAt": "2026-09-25T02:04:11.000Z",
        "error": null
      },
      "lastStatement": {
        "runId": "cmg3r7c0n0013run0001abcd",
        "periodStart": "2026-09-23T22:00:00.000Z",
        "periodEnd": "2026-09-24T22:00:00.000Z"
      },
      "unmatched": 1,
      "unmatchedAmount": 75,
      "exceptions": 1,
      "notReceived": 1,
      "balance": {
        "periodDays": 30,
        "opening": 1203.55,
        "collections": 48250.5,
        "unpaids": -350,
        "refunds": -499,
        "fees": -612.4,
        "disbursements": -12000,
        "settlements": -33000,
        "other": 0,
        "closing": 2992.65,
        "computedClosing": 2992.65,
        "difference": 0
      }
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403Plan does not include the API or reconciliation.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "This feature is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/accounts" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"
GET/api/v1/accounting/referral-links

Returns tracked sign-up links for the accounting systems CentraPoint partners with, so you can show a "Don't have Xero? Sign up" link in your own app. Only active partner programmes are returned; the list can be empty. Each url is specific to your organisation. Available on any plan with API access: signing up for an accounting system does not require CentraPoint's accounting sync feature.

200Active referral links.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredReferralLink[]
Show fields
data fields
FieldTypeDescription
connectorrequiredstring

Accounting connector type, e.g. xero, quickbooks, zoho_books, sage_one_za.

namerequiredstring

Display name of the accounting system.

programrequiredstring

Name of the partner programme.

urlrequiredstring (uri)

Signed CentraPoint redirect (/r/accounting/{connector}?s=…) that records the click for your organisation and forwards to the vendor's sign-up page. Works without a CentraPoint login; do not modify it.

Example
{
  "data": [
    {
      "connector": "xero",
      "name": "Xero",
      "program": "Xero App Partner",
      "url": "https://app.centrapoint.co.za/r/accounting/xero?s=cpQ2VudHJhUG9pbnQx.bG9uZy1zaWduYXR1cmUx"
    },
    {
      "connector": "zoho_books",
      "name": "Zoho Books",
      "program": "Zoho Affiliate",
      "url": "https://app.centrapoint.co.za/r/accounting/zoho_books?s=cpQ2VudHJhUG9pbnQx.c2Vjb25kLXNpZ25hdHVyZQ"
    }
  ]
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}
curl -X GET "https://app.centrapoint.co.za/api/v1/accounting/referral-links" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get your organisation and entitlements#

GET/api/v1/me

The calling API key's organisation, plan and full entitlements: built-in feature flags and limits (with per-organisation overrides applied) plus custom features. Use it in your own apps to decide what to enable.

Responses#

200Organisation, plan, entitlements and key.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
apiVersionrequiredstring

Version of this API, e.g. 1.17.0. Integrations that need a feature can stop when it is older (subscription imports need 1.16.0, tax needs 1.17.0).

taxrequiredobject

Your organisation's tax setting (Settings > Tax) as it is charged: what CentraPoint puts on subscription charges, payment links and document lines that carry no rate of their own. Since 1.17.0.

Show fields
tax fields
FieldTypeDescription
enabledrequiredboolean

Whether tax is charged at all: switched on with a rate above 0.

namerequiredstring

Label printed on documents.

raterequirednumber

The rate that is charged, in percent. 0 when enabled is false, whatever rate is still saved.

inclusiverequiredboolean

true: prices already include tax. false: tax is added on top.

configuredrequiredboolean

false: Settings > Tax was never saved, so the legacy company VAT rate applies, added on top (15% unless the company settings say otherwise).

taxNumberrequiredstring | null

Tax number printed on your documents, if any.

capabilitiesrequiredobject
Show fields
capabilities fields
FieldTypeDescription
externalSubscriptionsrequiredboolean

Whether subscription imports (collectionMethod: external) are accepted now. false for a short time while CentraPoint is being updated; creates then answer 409 external_imports_unavailable.

savedCardsboolean

Customers can save a card (a gateway that saves cards, Netcash Pay Now).

chargeSavedCardsboolean

Saved cards can be charged (a Netcash Debit Orders gateway with Card debits).

accountStandingboolean

The account standing rules are switched on (Settings → Cards & standing).

tenantrequiredobject
Show fields
tenant fields
FieldTypeDescription
idstring
namestring
slugstring
accountNumberstring | null
statusstring
kindstring
billingCyclestring | null

How your CentraPoint plan is paid: monthly or yearly.

pendingBillingCyclestring | null

A switch of billingCycle scheduled for the end of the paid period (e.g. monthly after a paid year), else null. Since 1.22.0.

trialEndsAtstring (date-time) | null
currentPeriodEndstring (date-time) | null
planrequiredobject
Show fields
plan fields
FieldTypeDescription
codestring
namestring
currencystring

Since 1.22.0.

priceMonthlynumber

Price of the plan per month (0: priced on request). Since 1.22.0.

priceYearlynumber

Price of the plan per year when paid yearly: 12 x the monthly price less the yearly discount (0: priced on request). Since 1.22.0.

yearlyDiscountPercentnumber

What paying yearly saves against 12 monthly payments, in percent to two decimals. Since 1.22.0.

entitlementsrequiredobject
Show fields
entitlements fields
FieldTypeDescription
featuresobject

Built-in flags, e.g. featRecurring, with per-organisation overrides applied.

limitsobject

Built-in limits, e.g. maxUsers; null = unlimited.

customobject

Custom features keyed by feature key.

complianceobject

Business verification (KYB). Until approved is true only sandbox gateways can take payments and live payment requests return 403 compliance_required.

Show fields
compliance fields
FieldTypeDescription
statusstring

One of: not_started, submitted, in_review, changes_requested, approved, rejected, expired

approvedboolean
apiKeyrequiredobject | null
Show fields
apiKey fields
FieldTypeDescription
namestring
prefixstring
createdAtstring (date-time)
permissionsstring[]

Extra permissions of this key (1.19.0). cards:charge: may charge customers' saved cards (POST /api/v1/customers/{id}/cards/{cardId}/charges). Allowed per key under Settings → API keys.

One of: cards:charge

Example
{
  "tenant": {
    "id": "cmg0t1n2t0001ten0001abcd",
    "name": "Acme (Pty) Ltd",
    "slug": "acme",
    "accountNumber": "CP100042",
    "status": "active",
    "kind": "customer",
    "billingCycle": "monthly",
    "pendingBillingCycle": null,
    "trialEndsAt": null,
    "currentPeriodEnd": "2026-10-31T21:59:59.000Z"
  },
  "plan": {
    "code": "business",
    "name": "Business",
    "currency": "ZAR",
    "priceMonthly": 1999,
    "priceYearly": 19990,
    "yearlyDiscountPercent": 16.67
  },
  "compliance": {
    "status": "approved",
    "approved": true
  },
  "entitlements": {
    "features": {
      "featInvoicing": true,
      "featPaymentLinks": true,
      "featRecurring": true,
      "featDebitOrders": true,
      "featApi": true,
      "featReports": true,
      "featCustomerPortal": true,
      "featCoupons": true
    },
    "limits": {
      "maxUsers": 10,
      "maxProviders": null,
      "maxCustomers": null,
      "maxMonthlyTransactions": null,
      "maxApiKeys": 5,
      "maxMandates": 500
    },
    "custom": {
      "sms_notifications": {
        "enabled": true,
        "limit": 1000,
        "label": "SMS notifications"
      }
    }
  },
  "apiKey": {
    "name": "Production",
    "prefix": "cp_1a2b3c4d",
    "createdAt": "2026-09-01T10:00:00.000Z"
  }
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Check one entitlement#

GET/api/v1/entitlements/{key}

Whether your organisation has a feature. key is a built-in flag (e.g. featRecurring), a built-in limit (e.g. maxUsers) or a custom feature key (e.g. sms_notifications). Any valid API key may call this, even when the plan has no REST API.

Path parameters#

Path parameters
FieldTypeDescription
keyrequiredstring

Responses#

200The entitlement.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
keyrequiredstring
enabledrequiredboolean

For limits: false only when the limit is 0.

limitrequiredinteger | null

The limit value; null = unlimited or not a limit.

Example
{
  "key": "featRecurring",
  "enabled": true,
  "limit": null
}
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
404Unknown key.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "not_found",
  "message": "Feature not found"
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Preview a change#

POST/api/v1/customer-subscriptions/{id}/preview-change

Same body as change-plan; nothing changes. Returns the current and new per-cycle amounts (subtotal, tax, total), the proration invoice (lines with billing periods, whether it is due now) and the next renewal invoice.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request body#

application/json · required

Request body fields
FieldTypeDescription
planIdstring
quantityinteger

≥ 1 · ≤ 10 000

itemsSubscriptionItemInput[]

The complete list of recurring lines (addon / metered) after the change; matched by code. Omit to keep the current ones.

Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
prorationstring

none: switch now, the new price applies from the next renewal. now: switch now and charge (or credit) the difference for the rest of the period; a frequency change starts a new period now. next_renewal: switch at the next renewal (pendingChange).

One of: none, now, next_renewal

default "none"

invoiceNowboolean

now: invoice / charge a positive difference immediately; false adds it to the next renewal. Credits always go to the next renewal.

default true

Responses#

200Preview a change

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/preview-change" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 5,
    "proration": "now"
  }'

Reactivate a subscription#

POST/api/v1/customer-subscriptions/{id}/reactivate

Reactivates a cancelled or expired subscription (or undoes a scheduled cancellation). Billing resumes on nextBillingAt (default now; the next billing run issues the charge, or chargeNow: true bills immediately). A subscription that never paid starts again as incomplete with a new first charge. Sends subscription.reactivated. External subscriptions are reactivated silently (no charge, email or webhook; chargeNow is refused with 409 external_subscription); then record the period with sync-period.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
nextBillingAtstring
chargeNowboolean

Responses#

200Reactivate a subscription

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/reactivate" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Record your platform's period (external subscriptions)#

POST/api/v1/customer-subscriptions/{id}/sync-period

For collectionMethod: external subscriptions only: records your platform's current period and status after its own renewal or status change. A period that starts where the recorded one ended counts as a renewal (cyclesBilled + 1); sending the recorded period and status again changes nothing. A scheduled cancellation moves to the new period end. A period that starts and ends before the recorded one with the same status is refused with 409 stale_period (an older update arriving late); keep the recorded start to correct the current period. Two identical calls at the same time record one renewal. Nothing is charged, emailed or sent as a webhook.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
currentPeriodStartrequiredstring

YYYY-MM-DD (06:00 SAST) or ISO date-time.

currentPeriodEndrequiredstring

After currentPeriodStart, at most three years later. In the future for active and trialing.

statusstring

Default: unchanged. past_due while your platform waits for payment; trialing: the period end is the trial end.

One of: active, trialing, past_due

Responses#

200The subscription with the recorded period.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`not_external`: CentraPoint bills this subscription itself. `invalid_state`: the subscription is cancelled or expired (reactivate it first). `stale_period`: the period starts and ends before the recorded one and the status is the same (a late retry): nothing changed. `concurrent_update`: other updates of the subscription kept winning while this one was applied: nothing changed, send it again.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
notExternal
{
  "error": "not_external",
  "message": "sync-period is only for subscriptions with collectionMethod external: CentraPoint bills this one itself"
}
stalePeriod
{
  "error": "stale_period",
  "message": "The recorded period (2026-10-31T04:00:00.000Z to 2026-11-30T04:00:00.000Z) is later than this one, so this looks like an older update that arrived late. Nothing changed."
}
concurrentUpdate
{
  "error": "concurrent_update",
  "message": "The subscription kept changing while this sync-period was applied (other updates at the same time). Nothing changed: send it again."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/sync-period" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPeriodStart": "2026-10-31",
    "currentPeriodEnd": "2026-11-30",
    "status": "active"
  }'

Add credit#

POST/api/v1/customer-subscriptions/{id}/credit

Credit (price-list amount) taken off the next charge(s); credit left over carries to later charges. Sends subscription.updated.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountrequirednumber

> 0

descriptionstring

max 500 chars

Responses#

200Add credit

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/credit" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150,
    "description": "Downtime credit"
  }'

Discount the next renewal#

POST/api/v1/customer-subscriptions/{id}/discount

One-off discount on the next renewal: percent of the recurring amount, or a fixed amount.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
percentnumber

> 0 · ≤ 100

amountnumber

> 0

descriptionstring

Responses#

200Discount the next renewal

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/discount" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "percent": 20
  }'

Cancel a scheduled change#

DELETE/api/v1/customer-subscriptions/{id}/pending-change

Drops the change scheduled for the next renewal.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200Cancel a scheduled change

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X DELETE "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/pending-change" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List items#

GET/api/v1/customer-subscriptions/{id}/items

Live lines: add-ons, metered lines and one-time lines not billed yet.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200List items

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
dataSubscriptionItem[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Add an item#

POST/api/v1/customer-subscriptions/{id}/items

one_time lines go on the next charge. Recurring lines change the per-cycle amount; proration as for change-plan.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
prorationstring

One of: none, now, next_renewal

invoiceNowboolean

Responses#

201Add an item

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
changeSubscriptionChangePreview
Show fields
change fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

chargeobject | null

Proration charge issued now: {method: invoice, invoiceId, invoiceNumber, payUrl} or {method: token, transactionId, status}.

400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "external_subscription",
  "message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "website_alias",
    "description": "Website alias",
    "unitAmount": 250,
    "quantity": 3,
    "proration": "now"
  }'

Replace the recurring items#

PUT/api/v1/customer-subscriptions/{id}/items

Sets the complete list of recurring (addon / metered) lines; matched by code (metered usage kept).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
itemsrequiredSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
prorationstring

One of: none, now, next_renewal

invoiceNowboolean

Responses#

200Replace the recurring items

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
changeSubscriptionChangePreview
Show fields
change fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

chargeobject | null

Proration charge issued now: {method: invoice, invoiceId, invoiceNumber, payUrl} or {method: token, transactionId, status}.

400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PUT "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Update an item#

PATCH/api/v1/customer-subscriptions/{id}/items/{itemId}

Change description, unitAmount or quantity (with proration).

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring
itemIdrequiredstring

Item id or its code.

Request body#

application/json · required

Request body fields
FieldTypeDescription
descriptionstring
unitAmountnumber
quantityinteger
metadataobject
prorationstring

One of: none, now, next_renewal

invoiceNowboolean

Responses#

200Update an item

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
changeSubscriptionChangePreview
Show fields
change fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

chargeobject | null

Proration charge issued now: {method: invoice, invoiceId, invoiceNumber, payUrl} or {method: token, transactionId, status}.

400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X PATCH "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Remove an item#

DELETE/api/v1/customer-subscriptions/{id}/items/{itemId}

Query proration = none (default) | now | next_renewal.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring
itemIdrequiredstring

Item id or its code.

Query parameters#

Query parameters
FieldTypeDescription
prorationstring

One of: none, now, next_renewal

Responses#

200Remove an item

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time) | null

When the subscription ends (scheduled cancellation or fixed term).

cancelAtPeriodEndrequiredboolean
cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

A change scheduled for the next renewal (proration: next_renewal).

Show fields
pendingChange fields
FieldTypeDescription
planIdstring
quantityinteger
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
amountnumber
requestedAtstring (date-time)
effectiveAtstring (date-time)
changeSubscriptionChangePreview
Show fields
change fields
FieldTypeDescription
objectstring

One of: subscription_change_preview

subscriptionIdstring
requestedProrationstring
prorationstring

What will apply (e.g. none when there is no paid period to prorate).

notestring | null
effectiveAtstring (date-time)
currencystring
currentobject
Show fields
current fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextobject
Show fields
next fields
FieldTypeDescription
planIdstring
planNamestring
quantityinteger
frequencystring
amountnumber
itemsSubscriptionItemInput[]
Show fields
items fields
FieldTypeDescription
codestring

max 100 chars

descriptionrequiredstring

max 500 chars

unitAmountrequirednumber

Negative only for one_time (credit).

quantityinteger

≥ 1 · ≤ 100 000 · default 1

kindstring

One of: addon, metered, one_time

default "addon"

metadataobject
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

prorationInvoiceobject | null
Show fields
prorationInvoice fields
FieldTypeDescription
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
dueNowboolean
creditToNextRenewalnumber
periodStartstring (date-time)
periodEndstring (date-time)
resetsPeriodboolean
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

nextInvoiceobject | null
Show fields
nextInvoice fields
FieldTypeDescription
datestring (date-time) | null
periodStartstring (date-time) | null
periodEndstring (date-time) | null
linesobject[]
Show fields
lines fields
FieldTypeDescription
descriptionstring
amountnumber
periodStartstring (date-time) | null
periodEndstring (date-time) | null
subtotalnumber

Price-list amount.

taxnumber
totalnumber

What the customer pays.

chargeobject | null

Proration charge issued now: {method: invoice, invoiceId, invoiceNumber, payUrl} or {method: token, transactionId, status}.

400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X DELETE "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Record metered usage#

POST/api/v1/customer-subscriptions/{id}/items/{itemId}/usage

Adds (increment, default) or sets usage of a metered item for the current period. Billed at the next renewal, then reset. Send an Idempotency-Key to avoid double counting on retries.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring
itemIdrequiredstring

Item id or its code.

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
quantityrequiredinteger
actionstring

One of: increment, set

Responses#

200Record metered usage

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId/usage" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 120
  }'

List a subscription's invoices#

GET/api/v1/customer-subscriptions/{id}/invoices

Newest first. Each invoice has the fields of GET /api/v1/invoices/{id} (billing period as inclusive YYYY-MM-DD dates, lines with details and their own periods), plus charge and cycle.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Query parameters#

Query parameters
FieldTypeDescription
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200List a subscription's invoices

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredSubscriptionInvoice[]
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: invoice

numberrequiredstring
statusrequiredstring

As on the Invoice object: partially_paid for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing cycle the invoice covers (YYYY-MM-DD, inclusive), or null (setup fee, re-collection).

periodEndrequiredstring (date) | null

Last day of the billing cycle (YYYY-MM-DD, inclusive): the day before the next billing date.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
chargerequiredstring | null

One of: first, cycle, recovery, setup, proration, null

cyclerequiredinteger | null
hasMorerequiredboolean
nextCursorrequiredstring | null
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/invoices" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

List a subscription's payments#

GET/api/v1/customer-subscriptions/{id}/payments

Payment attempts (transactions), newest first. Filter with status.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Query parameters#

Query parameters
FieldTypeDescription
statusstring
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200List a subscription's payments

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredSubscriptionPayment[]
Show fields
data fields
FieldTypeDescription
idstring
objectstring

One of: payment

referencestring
statusstring
amountnumber
taxAmountnumber | null
currencystring
gatewaystring
sandboxboolean

true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives.

invoiceIdstring | null
chargestring | null
cycleinteger | null
periodStartstring | null
periodEndstring | null
renewalboolean
paidAtstring (date-time) | null
createdAtstring (date-time)
hasMorerequiredboolean
nextCursorrequiredstring | null
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/payments" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Change amount or next charge date#

POST/api/v1/subscriptions/{id}/update

Changes the amount (what the payer pays) and/or next charge date (YYYY-MM-DD). In place where the gateway supports it (PayFast and Netcash Pay Now: amount and date; result.mode: updated). Otherwise an amount change uses the replace flow: the payer is emailed a new recurring checkout at the new amount (result.mode: replace, result.payUrl); once it is paid the old gateway subscription is cancelled (Netcash DeleteSubscription) and subscription.cancelled is sent for the old one. While that checkout is unpaid, a replacement at the same amount emails the same link again (same paymentLinkId / payUrl) instead of a second one; a replacement at another amount deactivates it (if the payer still completes it, it replaces the subscription and the newer link is deactivated); two replacements at the same time leave one open link. If the payer completes one checkout link twice, only the first payment replaces the subscription: the card subscription the second one started is cancelled at the gateway where the gateway can (otherwise the report says so, and it keeps collecting until you cancel it on the gateway's dashboard) and that payment is reported to your staff to refund. When the subscription is replaced, its unpaid retry links are deactivated. replace: false refuses instead. A token that collects a customer subscription must be changed through the customer subscription.

Invoice-linked subscriptions (started by a recurring payment link created with invoiceId) invoice every payment with a copy of the latest invoice's lines, so their amount is those lines' total and cannot change: another amount returns 409 invoice_linked and nothing is changed (a new nextDate is still accepted). A subscription whose amount was changed before 1.14.1 and no longer matches its lines can be set back to the lines total. Only the current replacement checkout replaces an invoice-linked subscription: a payment on an earlier one leaves the subscription as it is and is reported to your staff (audit log payment.renewal_unallocated and a notification). To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountnumber
nextDatestring (date)
replaceboolean

default true

sendEmailboolean

default true

Responses#

200Change amount or next charge date

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

resultobject
Show fields
result fields
FieldTypeDescription
modestring

One of: updated, replace

payUrlstring | null
paymentLinkIdstring | null
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`invoice_linked`: the subscription is invoice-linked and the amount would change. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
Example
{
  "error": "invoice_linked",
  "message": "This subscription is billed with invoice INV-000042: every payment is invoiced with a copy of its lines (R 299,00), so an amount change cannot use another amount. To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/id/update" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 599
  }'

Retry a failed charge#

POST/api/v1/subscriptions/{id}/retry

Re-collects the latest missed charge that has not been re-collected yet: a failed gateway renewal or charged retry of this subscription (a failed retry stands for the charge it retried). A payer's declined attempt on a retry link or replacement checkout is not a missed charge, and neither is a failed renewal of the card subscription a replacement checkout started (retry that subscription instead). Tokens CentraPoint can charge itself are charged now (mode: charged); otherwise the payer is emailed a once-off payment link for the amount (mode: payment_link; an earlier unpaid retry link for the same charge is deactivated). A charge is re-collected once: by a completed charged retry, a paid retry link, or a charged retry that is still pending (until the gateway reports its result). When no missed charge is left to re-collect, a subscription that never missed a charge is collected now (amount, or the subscription amount); one whose missed charges were all re-collected returns 409 nothing_to_retry unless you send amount, which is then collected now. Retries of one subscription are handled one at a time, so two calls at once cannot re-collect a charge twice.

For a subscription started by a payment link, a charged retry is recorded as a collection of that link, like a gateway renewal: the transaction has renewal: true (and retry: true in the charges list) and sends subscription.charged / subscription.payment_failed. Charged retries of other subscriptions have renewal: false.

Invoice-linked subscriptions (recurring payment link with invoiceId): a retry needs a missed charge that was not re-collected yet (else 409 nothing_to_retry, also with amount) and the invoice lines' total, which is the default (another amount returns 409 invoice_linked). The retry payment (charged, or the retry link once paid) is invoiced exactly once, like a renewal, for the period after the latest invoice. A second payment for a charge that was already re-collected (e.g. an earlier retry link the payer was still paying) is not invoiced: it is reported to your staff (audit log payment.renewal_unallocated and a notification) to refund or allocate.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
amountnumber
sendEmailboolean

Responses#

200Retry a failed charge

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
objectstring
subscriptionIdstring
modestring

One of: charged, payment_link

transactionIdstring
statusstring
payUrlstring
paymentLinkIdstring
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
409`nothing_to_retry`: no missed charge is left to re-collect (none, or each was re-collected or its charged retry is still pending) and either no `amount` was sent to a subscription that missed a charge before, or the subscription is invoice-linked (with or without `amount`). `invoice_linked`: `amount` differs from the invoice lines' total of an invoice-linked subscription. Nothing changed.

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
nothingToRetry
{
  "error": "nothing_to_retry",
  "message": "Every failed charge of this subscription was already re-collected (or a retry is still pending)"
}
invoiceLinked
{
  "error": "invoice_linked",
  "message": "This subscription is billed with invoice INV-000042: every payment is invoiced with a copy of its lines (R 299,00), so a retry cannot use another amount. To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines."
}
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/id/retry" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

List charges#

GET/api/v1/subscriptions/{id}/charges

Every charge of the subscription, newest first: first payment, gateway renewals, retries (charged, and payments or declined attempts on retry links) and payments or declined attempts on its replacement checkouts. The renewals of the card subscription a replacement checkout started are that subscription's charges.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Query parameters#

Query parameters
FieldTypeDescription
limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200List charges

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredSubscriptionCharge[]
Show fields
data fields
FieldTypeDescription
idstring
objectstring

One of: charge

referencestring
amountnumber
currencystring
statusstring
renewalboolean

A collection after the first payment: a gateway renewal, or a charged retry of a subscription started by a payment link (retries re-collect a renewal).

retryboolean

A retry of a failed charge (POST /api/v1/subscriptions/{id}/retry): a charged retry, or a payment or declined attempt through a retry payment link. A declined retry is not a new missed charge.

descriptionstring | null
paidAtstring (date-time) | null
createdAtstring (date-time)
hasMorerequiredboolean
nextCursorrequiredstring | null
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

List migrations#

GET/api/v1/subscriptions/migrations

Newest first; summary counts migrations per status.

Query parameters#

Query parameters
FieldTypeDescription
statusstring
qstring

Email, name or legacy reference contains.

limitinteger

1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20.

≥ 1 · ≤ 100 · default 20

startingAfterstring

Cursor: the id of the last item of the previous page (nextCursor). Must be an id from the same list.

Responses#

200List migrations

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
datarequiredSubscriptionMigration[]
Show fields
data fields
FieldTypeDescription
idstring
objectstring

One of: subscription_migration

statusstring

One of: pending, link_sent, authorised, legacy_cancelled, legacy_cancel_failed, cancelled, failed

payerNamestring
emailstring
phonestring | null
amountnumber
currencystring
frequencystring
nextDatestring (date-time) | null
legacyReferencestring
legacyGatewaystring
externalReferencestring | null
cancelLegacystring

One of: on_authorised, manual

providerIdstring | null
customerIdstring | null
subscriptionIdstring | null

The CentraPoint customer subscription.

paymentLinkIdstring | null
lastErrorstring | null
notesstring | null
linkSentAtstring | null
authorisedAtstring | null
legacyCancelledAtstring | null
sourcestring
createdAtstring
updatedAtstring
hasMorerequiredboolean
nextCursorrequiredstring | null
summaryobject
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Migrate legacy subscriptions#

POST/api/v1/subscriptions/migrations

One legacy subscription (201; 200 when the legacyReference exists) or {subscriptions: [...]} (up to 500; a result per row). CentraPoint creates the customer (by email) and an incomplete gateway customer subscription, and emails the payer a recurring checkout link to re-authorise their card. When paid the subscription activates and, with cancelLegacy: on_authorised, the legacy instruction is cancelled (Netcash DeleteSubscription with the legacy reference).

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

SubscriptionMigrationInput | object

Responses#

200Bulk import result, or an existing migration.

SubscriptionMigration | object

201Migrate legacy subscriptions

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
201 response fields
FieldTypeDescription
idstring
objectstring

One of: subscription_migration

statusstring

One of: pending, link_sent, authorised, legacy_cancelled, legacy_cancel_failed, cancelled, failed

payerNamestring
emailstring
phonestring | null
amountnumber
currencystring
frequencystring
nextDatestring (date-time) | null
legacyReferencestring
legacyGatewaystring
externalReferencestring | null
cancelLegacystring

One of: on_authorised, manual

providerIdstring | null
customerIdstring | null
subscriptionIdstring | null

The CentraPoint customer subscription.

paymentLinkIdstring | null
lastErrorstring | null
notesstring | null
linkSentAtstring | null
authorisedAtstring | null
legacyCancelledAtstring | null
sourcestring
createdAtstring
updatedAtstring
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/migrations" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "payerName": "Jane Smith",
    "email": "[email protected]",
    "amount": 115,
    "frequency": "monthly",
    "nextDate": "2026-11-01",
    "legacyReference": "INV-2019-0042"
  }'

Get a migration#

GET/api/v1/subscriptions/migrations/{id}

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring

Responses#

200Get a migration

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idstring
objectstring

One of: subscription_migration

statusstring

One of: pending, link_sent, authorised, legacy_cancelled, legacy_cancel_failed, cancelled, failed

payerNamestring
emailstring
phonestring | null
amountnumber
currencystring
frequencystring
nextDatestring (date-time) | null
legacyReferencestring
legacyGatewaystring
externalReferencestring | null
cancelLegacystring

One of: on_authorised, manual

providerIdstring | null
customerIdstring | null
subscriptionIdstring | null

The CentraPoint customer subscription.

paymentLinkIdstring | null
lastErrorstring | null
notesstring | null
linkSentAtstring | null
authorisedAtstring | null
legacyCancelledAtstring | null
sourcestring
createdAtstring
updatedAtstring
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

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

Migration actions#

POST/api/v1/subscriptions/migrations/{id}/{action}

send-link: (re)email the checkout link. cancel-legacy: DeleteSubscription at Netcash now. mark-legacy-cancelled {note?}: it was cancelled in the Netcash portal. cancel: abandon a migration the payer has not authorised.

Path parameters#

Path parameters
FieldTypeDescription
idrequiredstring
actionrequiredstring

One of: send-link, cancel-legacy, mark-legacy-cancelled, cancel

Request headers#

Request headers
FieldTypeDescription
Idempotency-Keystring

Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. POST /api/v1/invoices/{id}/send for one specific invoice). Retrying with the same key and the same body within 24 hours returns the stored response (with Idempotent-Replayed: true) instead of repeating the operation. Same key with a different body returns 409 idempotency_conflict. 5xx responses are not stored.

max 200 chars

Request body#

application/json · required

Request body fields
FieldTypeDescription
notestring

Responses#

200Migration actions

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
200 response fields
FieldTypeDescription
idstring
objectstring

One of: subscription_migration

statusstring

One of: pending, link_sent, authorised, legacy_cancelled, legacy_cancel_failed, cancelled, failed

payerNamestring
emailstring
phonestring | null
amountnumber
currencystring
frequencystring
nextDatestring (date-time) | null
legacyReferencestring
legacyGatewaystring
externalReferencestring | null
cancelLegacystring

One of: on_authorised, manual

providerIdstring | null
customerIdstring | null
subscriptionIdstring | null

The CentraPoint customer subscription.

paymentLinkIdstring | null
lastErrorstring | null
notesstring | null
linkSentAtstring | null
authorisedAtstring | null
legacyCancelledAtstring | null
sourcestring
createdAtstring
updatedAtstring
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
missing
{
  "error": "unauthorized",
  "message": "Missing or malformed API key"
}
invalid
{
  "error": "unauthorized",
  "message": "Invalid API key"
}
403API access is not included in your plan.
Example
{
  "error": "plan_restricted",
  "message": "API access is not included in your plan"
}
404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).

Headers

  • X-RateLimit-Limit – Requests allowed per 60-second window for this API key.
  • X-RateLimit-Remaining – Requests left in the current window.
  • X-RateLimit-Reset – Unix time (seconds) when the current window ends.
  • Retry-After – Seconds to wait before retrying.
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 120 requests per minute exceeded for this API key"
}
500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Example
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Code samples#

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/migrations/id/action" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"

Webhook events#

POSTSent by CentraPoint to your endpoint

Sent by CentraPoint to each HTTPS endpoint configured under Settings → Webhooks and subscribed to this event. Respond 2xx within 10 seconds. Failed deliveries are retried after 1m, 5m, 30m, 2h, 6h, 12h and 24h (8 attempts). Redirects are not followed. Deliveries may repeat and may arrive out of order.

  • payment.complete: Payment completed
  • payment.failed: Payment failed
  • payment.cancelled: Payment cancelled
  • payment.refunded: Payment fully refunded
  • payment.partially_refunded: Payment partially refunded
  • invoice.created: Invoice created
  • invoice.sent: Invoice sent
  • invoice.paid: Invoice fully paid
  • invoice.partially_paid: Invoice partially paid
  • invoice.cancelled: Invoice cancelled
  • eft.proof_received: EFT proof of payment received
  • eft.rejected: EFT proof rejected
  • eft.expired: EFT order expired
  • eft.cancelled: EFT order cancelled
  • reconciliation.completed: Reconciliation run completed
  • subscription.created: Customer subscription created
  • subscription.activated: Subscription activated (first payment completed)
  • subscription.charged: Subscription renewal charged
  • subscription.renewed: Customer subscription renewed
  • subscription.trial_ended: Customer subscription trial ended
  • subscription.payment_failed: Subscription renewal failed
  • subscription.past_due: Customer subscription past due
  • subscription.paused: Subscription paused
  • subscription.resumed: Subscription resumed
  • subscription.plan_changed: Customer subscription plan changed
  • subscription.updated: Customer subscription updated
  • subscription.cancelled: Subscription cancelled
  • subscription.expired: Customer subscription expired
  • checkout.completed: Checkout session completed
  • checkout.failed: Checkout session failed
  • quote.created: Quote created
  • quote.updated: Quote edited or moved back to draft
  • quote.sent: Quote marked sent
  • quote.accepted: Quote accepted
  • quote.declined: Quote declined
  • quote.expired: Quote expired
  • quote.invoiced: Quote converted to an invoice
  • credit_note.created: Credit note created
  • credit_note.issued: Credit note issued
  • credit_note.applied: Credit applied to an invoice
  • credit_note.refunded: Credit paid back
  • credit_note.voided: Credit note voided
  • payout.scheduled: Payout scheduled
  • payout.submitted: Payout submitted to Netcash
  • payout.paid: Payout paid
  • payout.failed: Payout failed
  • payout.cancelled: Payout cancelled
  • subscription.trial_ending: Customer subscription trial ending
  • subscription.reactivated: Customer subscription reactivated
  • customer.payment_method.added: Saved card added
  • customer.payment_method.removed: Saved card removed
  • customer.payment_method.expiring: Saved card expiring
  • customer.standing.changed: Account standing changed

Headers#

Webhook headers
FieldTypeDescription
CentraPoint-Eventrequiredstring

Event type.

CentraPoint-Deliveryrequiredstring

Delivery ID (constant across retries of this delivery).

CentraPoint-Signaturerequiredstring

t=<unix seconds>,v1=<hex HMAC-SHA256(signing secret, "<t>.<raw body>")>. Reject if t is more than 5 minutes old.

Payload: payment.complete, payment.failed, payment.cancelled, payment.refunded, payment.partially_refunded#

WebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…). Stable across retries, resends and endpoints; de-duplicate on it.

typerequiredstring

One of: payment.complete, payment.failed, payment.cancelled, payment.refunded, payment.partially_refunded

createdrequiredstring (date-time)
datarequiredWebhookPaymentData
Show fields
data fields
FieldTypeDescription
referencerequiredstring
statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountrequirednumber
currencyrequiredstring
typerequiredstring

One of: once, recurring, invoice, debit_order, eft, card_setup, card_debit

gatewayrequiredstring
sandboxrequiredboolean

true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives.

providerRefrequiredstring | null
paymentLinkIdrequiredstring | null
externalReferencerequiredstring | null

The payment link's externalReference, the EFT order's, or the one sent when charging a saved card (POST /api/v1/customers/{id}/cards/{cardId}/charges).

eftOrderIdrequiredstring | null

EFT order the payment belongs to (Manual EFT).

invoicerequirednull | object
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

renewalrequiredboolean
parentReferencerequiredstring | null
subscriptionIdrequiredstring | null
refundedAmountrequirednumber
paidAtrequiredstring (date-time) | null
Example payload
{
  "id": "evt_3f9a1c7b2e4d6f8091a2b3c4",
  "type": "payment.complete",
  "created": "2026-09-25T08:14:04.201Z",
  "data": {
    "reference": "CP-20260925-9F3A1C7B",
    "status": "complete",
    "amount": 499,
    "currency": "ZAR",
    "type": "once",
    "gateway": "payfast",
    "providerRef": "2458761",
    "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
    "externalReference": "ORDER-1001",
    "eftOrderId": null,
    "invoice": null,
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001"
    },
    "metadata": {
      "crmId": "0061x00000AbCdE"
    },
    "renewal": false,
    "parentReference": null,
    "subscriptionId": null,
    "refundedAmount": 0,
    "paidAt": "2026-09-25T08:14:03.512Z"
  }
}

Payload: invoice.created, invoice.sent, invoice.paid, invoice.partially_paid, invoice.cancelled#

InvoiceWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: invoice.created, invoice.sent, invoice.paid, invoice.partially_paid, invoice.cancelled

createdrequiredstring (date-time)
datarequiredInvoice
Show fields
data fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring

partially_paid is reported for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle.

periodEndrequiredstring (date) | null

Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean

true: line unitPrice and amount include tax, which was worked out of them. subtotal is always net of tax.

subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
paymentsrequiredInvoicePaymentEntry[]

Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions.

Show fields
payments fields
FieldTypeDescription
idrequiredstring

Offline payment ID or transaction ID.

sourcerequiredstring

One of: offline, transaction

originrequiredstring

Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.

methodrequiredstring

Offline: eft, cash, card, wallet or other. Transactions: the gateway type (e.g. payfast, manual_eft, netcash_debit).

statusrequiredstring

Offline payments are always complete.

One of: complete, partially_refunded, refunded

amountrequirednumber
refundedAmountrequirednumber

Refunded part of a transaction (0 for offline payments). Refunds reduce the invoice's amountPaid.

currencyrequiredstring
daterequiredstring (date-time)

When the money was received.

referencerequiredstring | null

Offline: the payer's / bank reference recorded. Transactions: the gateway's reference.

transactionReferencerequiredstring | null

Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}). Offline: null.

payUrlrequiredstring (uri) | null

Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency).

notesrequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example payload
{
  "id": "evt_7f3b01c9e1a5d2b8f4c6e0a3",
  "type": "invoice.created",
  "created": "2026-09-25T08:05:00.000Z",
  "data": {
    "id": "cmg2i9n0v0005inv0001abcd",
    "number": "INV-000042",
    "status": "draft",
    "externalReference": "ORDER-1001",
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "currency": "ZAR",
    "issueDate": "2026-09-24T22:00:00.000Z",
    "dueDate": "2026-10-08T21:59:59.000Z",
    "periodStart": "2026-10-01",
    "periodEnd": "2026-10-31",
    "lines": [
      {
        "description": "Website hosting - October",
        "details": "Business hosting plan\nDomain: nkosi.example.co.za",
        "quantity": 1,
        "unitPrice": 434.78,
        "taxRate": 15,
        "amount": 434.78,
        "periodStart": null,
        "periodEnd": null
      },
      {
        "description": "Domain renewal (zero-rated)",
        "details": null,
        "quantity": 1,
        "unitPrice": 120,
        "taxRate": 0,
        "amount": 120,
        "periodStart": "2026-10-01",
        "periodEnd": "2027-09-30"
      }
    ],
    "taxInclusive": false,
    "subtotal": 554.78,
    "taxAmount": 65.22,
    "total": 620,
    "amountPaid": 0,
    "amountDue": 620,
    "paidAt": null,
    "payments": [],
    "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
    "notes": "Payment due within 14 days.",
    "metadata": {
      "crmId": "0061x00000AbCdE"
    },
    "createdAt": "2026-09-25T08:05:00.000Z",
    "updatedAt": "2026-09-25T08:05:00.000Z"
  }
}

Payload: eft.proof_received, eft.rejected, eft.expired, eft.cancelled#

EftWebhookEvent fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: eft.proof_received, eft.rejected, eft.expired, eft.cancelled

createdrequiredstring (date-time)
datarequiredEftOrder
Show fields
data fields
FieldTypeDescription
idrequiredstring
referencerequiredstring

Unique deposit reference, e.g. EFT-7K3Q9P2M (prefix configurable, 8 characters without 0/O/1/I/L). Also the payment reference of the order's transaction.

statusrequiredstring

One of: awaiting_payment, awaiting_review, paid, rejected, expired, cancelled

amountrequirednumber
currencyrequiredstring
descriptionrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

customerrequirednull | object
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
bankDetailsrequiredobject

Your bank account from the Manual EFT gateway. Show these to the payer.

Show fields
bankDetails fields
FieldTypeDescription
bankNamerequiredstring
accountNamerequiredstring
accountNumberrequiredstring
branchCoderequiredstring
accountTyperequiredstring

One of: current, savings, transmission

paymentReferencerequiredstring

The reference the payer must use on the transfer (same as reference).

payUrlrequiredstring (uri)

Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404.

proofsrequiredobject[]
Show fields
proofs fields
FieldTypeDescription
idrequiredstring
fileNamerequiredstring
contentTyperequiredstring

One of: application/pdf, image/png, image/jpeg

sizerequiredinteger
sourcerequiredstring

Who uploaded it: your system via the API, staff in the dashboard, or the payer on the payer page.

One of: api, dashboard, payer

createdAtrequiredstring (date-time)
rejectionReasonrequiredstring | null
expiresAtrequiredstring (date-time) | null
reviewedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
Example payload
{
  "id": "evt_5c7e9a1b3d5f7a9c1e3b5d7f",
  "type": "eft.proof_received",
  "created": "2026-09-25T09:12:01.000Z",
  "data": {
    "id": "cmg3e1f2t0009eft0001abcd",
    "reference": "EFT-7K3Q9P2M",
    "status": "awaiting_review",
    "amount": 1250,
    "currency": "ZAR",
    "description": "Order #1001",
    "externalReference": "ORDER-1001",
    "metadata": {
      "cartId": "c_8841"
    },
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001"
    },
    "bankDetails": {
      "bankName": "FNB",
      "accountName": "Example Traders (Pty) Ltd",
      "accountNumber": "62000000000",
      "branchCode": "250655",
      "accountType": "current"
    },
    "paymentReference": "EFT-7K3Q9P2M",
    "payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
    "proofs": [
      {
        "id": "cmg3p0r0f0011prf0001abcd",
        "fileName": "proof.pdf",
        "contentType": "application/pdf",
        "size": 184213,
        "source": "payer",
        "createdAt": "2026-09-25T09:12:00.000Z"
      }
    ],
    "rejectionReason": null,
    "expiresAt": "2026-10-02T08:00:00.000Z",
    "reviewedAt": null,
    "paidAt": null,
    "createdAt": "2026-09-25T08:00:00.000Z"
  }
}

Payload: reconciliation.completed#

ReconciliationWebhookEvent fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: reconciliation.completed

createdrequiredstring (date-time)
datarequiredobject
Show fields
data fields
FieldTypeDescription
runIdrequiredstring
statusrequiredstring

One of: processing, failed, balanced, exceptions

exceptionsrequiredinteger
lineCountrequiredinteger
statementDaterequiredstring (date-time) | null
totalsrequiredReconciliationTotals

Positive sums of the statement lines in each category. Settlements, unlinked fees and balance lines are counted here but are not items.

Show fields
totals fields
FieldTypeDescription
receiptsrequirednumber

Collections.

feesrequirednumber
refundsrequirednumber
payoutsrequirednumber

Transfers to your own bank account (same as settlements).

settlementsrequirednumber

Transfers to your own bank account.

disbursementsrequirednumber

Creditor, salary and refund payouts, net of returns.

unpaidsrequirednumber

Returned debit orders, reversals, chargebacks and declines.

accountrequirednull | ReconciliationRunAccount

As on the run (null for CSV imports).

Show fields
account fields
FieldTypeDescription
idrequiredstring | null

Stable account id, one per service key (the key itself is never returned). Null for runs from before accounts.

providersrequiredReconciliationProvider[]

Gateways sharing the account when the run was created.

Show fields
providers fields
FieldTypeDescription
idrequiredstring

Payment gateway (provider) ID.

namerequiredstring
typerequiredstring

netcash, netcash_paynow or netcash_creditor. A gateway still set up with the retired Netcash Recurring Card module shows netcash_recurring until it is converted to netcash_paynow.

summaryrequiredobject
Show fields
summary fields
FieldTypeDescription
matchedrequiredinteger
unmatchedrequiredinteger
notReceivedrequiredinteger
balancerequiredReconciliationBalance

Signed balance view: money in positive, money out negative.

Show fields
balance fields
FieldTypeDescription
openingrequirednumber | null

Opening balance line of the statement, when present.

collectionsrequirednumber
unpaidsrequirednumber
refundsrequirednumber
feesrequirednumber
disbursementsrequirednumber

Creditor, salary and refund payouts.

settlementsrequirednumber

Transfers to your own bank account.

otherrequirednumber
closingrequirednumber | null

Closing balance line of the statement, when present.

computedClosingrequirednumber | null

Opening balance plus every line.

differencerequirednumber | null

closing minus computedClosing; non-zero means lines are missing.

Example payload
{
  "id": "evt_5c7e9a1b3d5f7a9c1e3b5d7f",
  "type": "reconciliation.completed",
  "created": "2026-09-25T09:12:01.000Z",
  "data": {
    "runId": "cmg3r7c0n0013run0001abcd",
    "status": "exceptions",
    "exceptions": 2,
    "lineCount": 42,
    "statementDate": "2026-09-24T22:00:00.000Z",
    "totals": {
      "receipts": 48250.5,
      "fees": 612.4,
      "refunds": 499,
      "payouts": 33000,
      "settlements": 33000,
      "disbursements": 12000,
      "unpaids": 350
    },
    "account": {
      "id": "acct_3f9a1c7b20d4e5f6",
      "providers": [
        {
          "id": "cmg3prov0000paynow000001",
          "name": "Card payments",
          "type": "netcash_paynow"
        },
        {
          "id": "cmg3prov0000recur0000002",
          "name": "Subscriptions",
          "type": "netcash_paynow"
        },
        {
          "id": "cmg3prov0000credit000003",
          "name": "Payouts",
          "type": "netcash_creditor"
        }
      ]
    },
    "summary": {
      "matched": 38,
      "unmatched": 1,
      "notReceived": 1,
      "balance": {
        "opening": 1203.55,
        "collections": 48250.5,
        "unpaids": -350,
        "refunds": -499,
        "fees": -612.4,
        "disbursements": -12000,
        "settlements": -33000,
        "other": 0,
        "closing": 2992.65,
        "computedClosing": 2992.65,
        "difference": 0
      }
    }
  }
}

Payload: subscription.created, subscription.renewed, subscription.trial_ended, subscription.past_due, subscription.plan_changed, subscription.updated, subscription.expired, subscription.trial_ending, subscription.reactivated#

CustomerSubscriptionWebhookEvent fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: subscription.activated, subscription.cancelled, subscription.created, subscription.expired, subscription.past_due, subscription.paused, subscription.payment_failed, subscription.plan_changed, subscription.reactivated, subscription.renewed, subscription.resumed, subscription.trial_ended, subscription.trial_ending, subscription.updated

createdrequiredstring (date-time)
datarequiredobject
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: customer_subscription

statusrequiredstring

scheduled: starts on a future startDate (then trialing or incomplete).

One of: scheduled, incomplete, trialing, active, past_due, paused, cancelled, expired

customerrequiredobject
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
planrequiredobject
Show fields
plan fields
FieldTypeDescription
idrequiredstring
namerequiredstring
packageIdrequiredstring
packageNamerequiredstring
collectionMethodrequiredstring

external: billed by your platform (mirror import); CentraPoint never charges, invoices, emails, reminds, duns or expires it and sends no subscription.* webhooks for it.

One of: gateway, debit_order, invoice, manual, external

collectedByCentraPointrequiredboolean

false for external subscriptions: CentraPoint does not collect them, so leave them out of income CentraPoint collects.

billedByrequiredstring | null

External subscriptions: the platform that bills it (metadata.importedFrom); otherwise null.

quantityrequiredinteger
amountrequirednumber

Amount per billing period: plan price × quantity, less a forever coupon.

currencyrequiredstring
frequencyrequiredstring

One of: daily, weekly, biweekly, monthly, quarterly, biannually, annually

billingCyclesrequiredinteger | null

From the plan; null = until cancelled.

cyclesBilledrequiredinteger
startedAtrequiredstring (date-time)
trialEndsAtrequiredstring (date-time) | null
currentPeriodStartrequiredstring (date-time) | null
currentPeriodEndrequiredstring (date-time) | null
nextBillingAtrequiredstring (date-time) | null

Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information.

endsAtrequiredstring (date-time)

updated with cancelAtPeriodEnd true.

cancelAtPeriodEndrequiredboolean

updated: a cancellation at period end was scheduled (true) or undone (false).

cancelledAtrequiredstring (date-time) | null
cancelReasonrequiredstring | null
pausedAtrequiredstring (date-time) | null
resumedAtrequiredstring (date-time) | null
dunningAttemptsrequiredinteger

Failed-payment retries so far (0 when paid up).

gatewayrequiredstring | null

Gateway type of the provider, e.g. payfast.

providerIdrequiredstring | null
paymentTokenIdrequiredstring | null

Gateway subscription/token collecting it (the same ID as the gateway subscription in GET /api/v1/subscriptions).

couponIdrequiredstring | null
externalReferencerequiredstring | null
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

sourcerequiredstring

One of: dashboard, api, checkout, portal

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
eventsobject[]

Only with ?include=events: the latest 100 timeline events, newest first.

Show fields
events fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: created, activated, trial_started, trial_ended, renewed, charge_issued, payment_failed, payment_recovered, dunning, paused, resumed, cancel_scheduled, cancel_unscheduled, cancelled, expired, plan_changed, updated, mandate_linked, reminder_sent

detailsrequiredobject | null
createdAtrequiredstring (date-time)
planAmountnumber

Plan part of amount (plan price x quantity after a forever coupon). amount = planAmount + recurring add-ons.

billingAnchorDayinteger | null

Day of month renewals fall on (clamped to the month end).

≥ 1 · ≤ 31

itemsSubscriptionItem[]

Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration).

Show fields
items fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: subscription_item

kindrequiredstring

addon: billed every cycle. metered: unitAmount x usage per period. one_time: next charge only (negative = credit).

One of: addon, metered, one_time

coderequiredstring | null

Your key for the line, e.g. website_alias (unique per subscription).

descriptionrequiredstring
unitAmountrequirednumber

Price-list amount per unit (same tax basis as plan prices).

quantityrequiredinteger
usageQuantityinteger

metered: usage recorded this period.

discountPercentnumber | null

one_time discount lines: percent of the recurring amount.

periodStartstring (date-time) | null
periodEndstring (date-time) | null
billedAtstring (date-time) | null
invoiceIdstring | null
amountrequirednumber

unitAmount x quantity (metered: x usageQuantity).

metadataobject | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
pendingChangeobject | null

updated: a change scheduled for the next renewal (or null when removed).

subscriptionIdrequiredstring

Same as id.

transactionIdstring | null

activated, renewed, payment_failed: the payment involved.

invoiceIdstring | null

activated, renewed, payment_failed: the invoice involved.

recoveredboolean

renewed only: true when an overdue payment was recovered.

reasonstring | null

payment_failed, past_due, cancelled, expired.

attemptinteger

past_due: dunning attempt.

previousPlanobject

plan_changed: { id, name } of the old plan.

Show fields
previousPlan fields
FieldTypeDescription
idstring
namestring
previousAmountnumber

plan_changed.

billingPeriodobject | null

Every event: the current billing period.

Show fields
billingPeriod fields
FieldTypeDescription
startstring (date-time) | null
endstring (date-time) | null
invoiceobject

When the event concerns an invoice (invoiceId): the invoice with its lines and billing period, as in the subscription invoices list.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: invoice

numberrequiredstring
statusrequiredstring

As on the Invoice object: partially_paid for draft/sent/overdue invoices that have received some money.

One of: draft, sent, overdue, partially_paid, paid, cancelled

externalReferencerequiredstring | null
currencyrequiredstring
issueDaterequiredstring (date-time)
dueDaterequiredstring (date-time) | null
periodStartrequiredstring (date) | null

First day of the billing cycle the invoice covers (YYYY-MM-DD, inclusive), or null (setup fee, re-collection).

periodEndrequiredstring (date) | null

Last day of the billing cycle (YYYY-MM-DD, inclusive): the day before the next billing date.

linesrequiredInvoiceLine[]
Show fields
lines fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when the invoice's taxInclusive is true.

taxRaterequirednumber

VAT percentage for this line.

amountrequirednumber

quantity × unitPrice (rounded to cents), excluding VAT, or including it when taxInclusive is true.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountPaidrequirednumber
amountDuerequirednumber

total − amountPaid.

paidAtrequiredstring (date-time) | null
chargerequiredstring | null

One of: first, cycle, recovery, setup, proration, null

cyclerequiredinteger | null
paymentobject

When the event concerns a payment (transactionId).

Show fields
payment fields
FieldTypeDescription
idstring
referencestring
amountnumber
currencystring
statusstring
invoiceIdstring | null
paidAtstring | null
prorationstring

plan_changed / updated: the proration that applied.

previousStatusstring

reactivated.

Example payload
{
  "id": "evt_7b1d3f5a9c2e4a6c8e0b2d4f",
  "type": "subscription.created",
  "created": "2026-10-12T08:10:05.000Z",
  "data": {
    "id": "cmg4s9d8e0005csb0001abcd",
    "object": "customer_subscription",
    "status": "trialing",
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "plan": {
      "id": "cmg4p1a2b0002pln0001abcd",
      "name": "Pro",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "packageName": "Acme Cloud"
    },
    "collectionMethod": "invoice",
    "quantity": 1,
    "amount": 499,
    "currency": "ZAR",
    "frequency": "monthly",
    "billingCycles": null,
    "cyclesBilled": 0,
    "startedAt": "2026-09-28T08:10:00.000Z",
    "trialEndsAt": "2026-10-12T08:10:00.000Z",
    "currentPeriodStart": null,
    "currentPeriodEnd": null,
    "nextBillingAt": "2026-10-12T08:10:00.000Z",
    "endsAt": null,
    "cancelAtPeriodEnd": false,
    "cancelledAt": null,
    "cancelReason": null,
    "pausedAt": null,
    "resumedAt": null,
    "dunningAttempts": 0,
    "gateway": null,
    "providerId": null,
    "paymentTokenId": null,
    "couponId": null,
    "externalReference": "SUB-CRM-1001-PRO",
    "metadata": {
      "crmDealId": "D-778"
    },
    "source": "api",
    "createdAt": "2026-09-28T08:10:00.000Z",
    "updatedAt": "2026-09-28T08:10:00.000Z",
    "subscriptionId": "cmg4s9d8e0005csb0001abcd"
  }
}

Payload: subscription.activated, subscription.charged, subscription.payment_failed, subscription.paused, subscription.resumed, subscription.cancelled#

SubscriptionWebhookEvent fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: subscription.activated, subscription.charged, subscription.payment_failed, subscription.cancelled, subscription.paused, subscription.resumed

createdrequiredstring (date-time)
datarequiredSubscriptionWebhookData
Show fields
data fields
FieldTypeDescription
idrequiredstring
statusrequiredstring

One of: active, paused, cancelled

frequencyrequiredstring | null

One of: monthly, quarterly, biannually, annually, null

amountrequirednumber | null

Amount of each collection.

currencyrequiredstring
gatewayrequiredstring

Gateway that bills the subscription, e.g. payfast, netcash_paynow.

paymentLinkIdrequiredstring | null

The recurring payment link that started it.

externalReferencerequiredstring | null

That link's externalReference.

metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
capabilitiesGatewaySubscriptionCapabilities

What the gateway supports for this subscription (GET /subscriptions/{id} and update responses).

Show fields
capabilities fields
FieldTypeDescription
cancelboolean
pauseboolean
resumeboolean
updateAmountboolean
updateNextDateboolean
chargeboolean
replaceboolean

The gateway type can change an amount by replacing the subscription (a new recurring checkout emailed to the payer). These capabilities describe the gateway module, not its current settings: a replacement also needs an enabled gateway that takes recurring payments in that currency now (for Netcash Pay Now, with Recurring card payments on), otherwise it answers 400 and nothing changes.

replacementLinkIdstring | null

Checkout link emailed to replace this subscription (new amount / re-authorised card).

subscriptionIdrequiredstring

Same as id.

paymentobject

activated / charged / payment_failed only: the payment that triggered the event.

Show fields
payment fields
FieldTypeDescription
referencerequiredstring
amountrequirednumber
currencyrequiredstring
statusrequiredstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

paidAtrequiredstring (date-time) | null
periodStartstring (date-time) | null

activated / charged / payment_failed only: when the paid period starts (the payment time). Null when the payment failed.

periodEndstring (date-time) | null

periodStart plus one billing interval. Null when periodStart is null.

Example payload
{
  "id": "evt_2a4c6e8f0b1d3f5a7c9e1b3d",
  "type": "subscription.activated",
  "created": "2026-10-25T08:14:05.000Z",
  "data": {
    "id": "cmg2s5b8k0007sub0001abcd",
    "status": "active",
    "frequency": "monthly",
    "amount": 499,
    "currency": "ZAR",
    "gateway": "payfast",
    "paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
    "externalReference": "SUB-ACME-PRO",
    "metadata": {
      "plan": "pro"
    },
    "createdAt": "2026-09-25T08:14:04.000Z",
    "updatedAt": "2026-09-25T08:14:04.000Z",
    "subscriptionId": "cmg2s5b8k0007sub0001abcd",
    "payment": {
      "reference": "CP-20260925-9F3A1C7B",
      "amount": 499,
      "currency": "ZAR",
      "status": "complete",
      "paidAt": "2026-09-25T08:14:03.512Z"
    },
    "periodStart": "2026-09-25T08:14:03.512Z",
    "periodEnd": "2026-10-25T08:14:03.512Z"
  }
}

Payload: checkout.completed, checkout.failed#

CheckoutWebhookEvent fields
FieldTypeDescription
idrequiredstring
typerequiredstring

One of: checkout.completed, checkout.failed

createdrequiredstring (date-time)
datarequiredCheckoutSession
Show fields
data fields
FieldTypeDescription
idrequiredstring
objectrequiredstring

One of: checkout_session

statusrequiredstring

expired: not completed and past expiresAt. A payment that completes later still moves the session to completed.

One of: pending, completed, failed, expired

sourcerequiredstring

api: created with this API; hosted: created by a payer on a shared checkout page.

One of: api, hosted

checkoutUrlrequiredstring | null

Hosted checkout URL while the session is pending or failed and not expired (null for hosted sessions).

packageIdrequiredstring | null
planIdrequiredstring | null

Preselected plan.

productIdrequiredstring | null
customerIdrequiredstring | null

Set once the payer's details are known.

subscriptionIdrequiredstring | null

Customer subscription created by the checkout.

couponCoderequiredstring | null
returnUrlrequiredstring | null
prefillrequiredobject
Show fields
prefill fields
FieldTypeDescription
emailstring
firstNamestring
lastNamestring
phonestring
companystring
metadatarequiredMetadata

Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, _ . : -; values up to 500 characters; at most 4000 characters as JSON. Returned as {} when empty.

transactionrequiredobject | null
Show fields
transaction fields
FieldTypeDescription
idstring
referencestring
statusstring

complete is the only status that means money was received. refunded / partially_refunded are set when a refund is recorded in the dashboard.

One of: pending, complete, failed, cancelled, refunded, partially_refunded

amountnumber
currencystring
discountAmountnumber | null
taxAmountnumber | null
paidAtstring (date-time) | null
expiresAtrequiredstring (date-time)
usedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example payload
{
  "id": "evt_9c1e3a5b7d9f1b3d5f7a9c1e",
  "type": "checkout.completed",
  "created": "2026-09-28T08:41:10.000Z",
  "data": {
    "id": "cmg5k1s2e0010cks0001abcd",
    "object": "checkout_session",
    "status": "completed",
    "source": "api",
    "checkoutUrl": null,
    "packageId": "cmg4p1a2b0001pkg0001abcd",
    "planId": "cmg4p1a2b0002pln0001abcd",
    "productId": null,
    "customerId": "cmg2c0s7t0003cust0001abcd",
    "subscriptionId": "cmg4s9d8e0005csb0001abcd",
    "couponCode": "WELCOME10",
    "returnUrl": "https://www.example.co.za/thanks",
    "prefill": {
      "email": "[email protected]",
      "firstName": "Thandi",
      "lastName": "Nkosi"
    },
    "metadata": {
      "signupId": "SU-9921"
    },
    "transaction": {
      "id": "cmg2t1x2y0009txn0001abcd",
      "reference": "CP-20260928-4B2D9E1A",
      "status": "complete",
      "amount": 449.1,
      "currency": "ZAR",
      "discountAmount": 49.9,
      "taxAmount": 58.58,
      "paidAt": "2026-09-28T08:41:00.000Z"
    },
    "expiresAt": "2026-09-29T08:30:00.000Z",
    "usedAt": "2026-09-28T08:41:00.000Z",
    "createdAt": "2026-09-28T08:30:00.000Z",
    "updatedAt": "2026-09-28T08:30:00.000Z"
  }
}

Payload: quote.created, quote.updated, quote.sent, quote.accepted, quote.declined, quote.expired, quote.invoiced#

QuoteWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: quote.created, quote.updated, quote.sent, quote.accepted, quote.declined, quote.expired, quote.invoiced

createdrequiredstring (date-time)
datarequiredQuote

Returned by every quote endpoint and sent as data in quote.* webhooks.

Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: quote

idrequiredstring
numberrequiredstring

Sequential quote number, e.g. QUO-000017.

statusrequiredstring

One of: draft, sent, accepted, declined, expired, invoiced

issueDaterequiredstring (date-time)
expiryDaterequiredstring (date-time) | null

End of the last valid day (SAST); null for no expiry.

periodStartrequiredstring (date) | null

First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null.

currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
notesrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null

The invoice the quote was converted into.

Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
statusrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

sentAtrequiredstring (date-time) | null
acceptedAtrequiredstring (date-time) | null
declinedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example payload
{
  "id": "evt_7f3b03c9e1a5d2b8f4c6e0a3",
  "type": "quote.created",
  "created": "2026-09-27T07:55:00.000Z",
  "data": {
    "object": "quote",
    "id": "cmg3q1a2b0001quo0001abcd",
    "number": "QUO-000017",
    "status": "draft",
    "issueDate": "2026-09-26T22:00:00.000Z",
    "expiryDate": "2026-10-26T21:59:59.000Z",
    "periodStart": null,
    "periodEnd": null,
    "currency": "ZAR",
    "taxInclusive": false,
    "subtotal": 5000,
    "taxAmount": 750,
    "total": 5750,
    "notes": "Valid for 30 days.",
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "invoice": null,
    "lineItems": [
      {
        "description": "Website redesign",
        "details": "5 pages, mobile layout\nTwo rounds of changes",
        "quantity": 1,
        "unitPrice": 4500,
        "amount": 4500,
        "taxRate": 15,
        "periodStart": null,
        "periodEnd": null
      },
      {
        "description": "Hosting setup",
        "details": null,
        "quantity": 1,
        "unitPrice": 500,
        "amount": 500,
        "taxRate": 15,
        "periodStart": null,
        "periodEnd": null
      }
    ],
    "sentAt": null,
    "acceptedAt": null,
    "declinedAt": null,
    "createdAt": "2026-09-27T07:55:00.000Z",
    "updatedAt": "2026-09-27T07:55:00.000Z"
  }
}

Payload: credit_note.created, credit_note.issued, credit_note.applied, credit_note.refunded, credit_note.voided#

CreditNoteWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: credit_note.created, credit_note.issued, credit_note.applied, credit_note.refunded, credit_note.voided

createdrequiredstring (date-time)
datarequiredCreditNote

Returned by every credit note endpoint and sent as data in credit_note.* webhooks.

Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: credit_note

idrequiredstring
numberrequiredstring

Sequential number, e.g. CN-000008.

statusrequiredstring

applied / refunded: fully used, mostly applied to invoices / paid back.

One of: draft, issued, applied, refunded, void

issueDaterequiredstring (date-time)
periodStartrequiredstring (date) | null

First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

periodEndrequiredstring (date) | null

Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null.

reasonrequiredstring | null
currencyrequiredstring
taxInclusiverequiredboolean
subtotalrequirednumber
taxAmountrequirednumber
totalrequirednumber
amountAppliedrequirednumber

Applied to invoices.

amountRefundedrequirednumber

Paid back, including scheduled payouts (released if the payout is cancelled or fails).

balancerequirednumber

total − amountApplied − amountRefunded.

customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
invoicerequiredobject | null
Show fields
invoice fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
externalReferencerequiredstring | null
lineItemsrequiredFinanceLine[]
Show fields
lineItems fields
FieldTypeDescription
descriptionrequiredstring
detailsrequiredstring | null

Detailed, multi-line description shown under description (plan features, usage, domain, reference...), or null.

quantityrequirednumber
unitPricerequirednumber

Excluding VAT, or including it when taxInclusive is true.

amountrequirednumber

quantity × unitPrice (rounded to cents).

taxRaterequirednumber | null

VAT percentage for this line.

periodStartrequiredstring (date) | null

First day of the line's own period (YYYY-MM-DD, inclusive) when it differs from the document period, or null.

periodEndrequiredstring (date) | null

Last day of the line's own period (YYYY-MM-DD, inclusive), or null.

historyrequiredobject[]
Show fields
history fields
FieldTypeDescription
atrequiredstring (date-time)
kindrequiredstring

One of: applied, refund, payout, manual, released

amountrequirednumber
refrequiredstring

Invoice number, payment reference, payout reference or manual reference.

notestring
refundsrequiredobject[]
Show fields
refunds fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
amountrequirednumber
transactionIdrequiredstring
payoutsrequiredobject[]
Show fields
payouts fields
FieldTypeDescription
idrequiredstring
referencerequiredstring
statusrequiredstring
amountrequirednumber
actionDaterequiredstring (date-time)
paidAtrequiredstring (date-time) | null
issuedAtrequiredstring (date-time) | null
voidedAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example payload
{
  "id": "evt_7f3b10c9e1a5d2b8f4c6e0a3",
  "type": "credit_note.created",
  "created": "2026-09-27T09:10:00.000Z",
  "data": {
    "object": "credit_note",
    "id": "cmg3c7d8e0002crn0001abcd",
    "number": "CN-000008",
    "status": "draft",
    "issueDate": "2026-09-27T09:10:00.000Z",
    "periodStart": "2026-09-01",
    "periodEnd": "2026-09-30",
    "reason": "Hosting downtime 12-14 September",
    "currency": "ZAR",
    "taxInclusive": false,
    "subtotal": 200,
    "taxAmount": 30,
    "total": 230,
    "amountApplied": 0,
    "amountRefunded": 0,
    "balance": 230,
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "CRM-1001",
      "email": "[email protected]"
    },
    "invoice": {
      "id": "cmg2i9n0v0005inv0001abcd",
      "number": "INV-000042",
      "externalReference": "ORDER-1001"
    },
    "lineItems": [
      {
        "description": "Service credit - downtime",
        "details": "Outage 12-14 September (3 days)",
        "quantity": 1,
        "unitPrice": 200,
        "amount": 200,
        "taxRate": 15,
        "periodStart": "2026-09-12",
        "periodEnd": "2026-09-14"
      }
    ],
    "history": [],
    "refunds": [],
    "payouts": [],
    "issuedAt": null,
    "voidedAt": null,
    "createdAt": "2026-09-27T09:10:00.000Z",
    "updatedAt": "2026-09-27T09:10:00.000Z"
  }
}

Payload: payout.scheduled, payout.submitted, payout.paid, payout.failed, payout.cancelled#

PayoutWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: payout.scheduled, payout.submitted, payout.paid, payout.failed, payout.cancelled

createdrequiredstring (date-time)
datarequiredPayout

Returned by every payout endpoint and sent as data in payout.* webhooks. Bank details are never included.

Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: payout

idrequiredstring
referencerequiredstring

Account reference in the Netcash batch, e.g. PAY-000031.

kindrequiredstring

One of: creditor, salary, refund

statusrequiredstring

One of: scheduled, submitted, paid, failed, cancelled

beneficiaryNamerequiredstring
beneficiaryEmailrequiredstring | null
bankNamerequiredstring | null
accountLast4requiredstring | null
amountrequirednumber
currencyrequiredstring

One of: ZAR

descriptionrequiredstring | null
statementRefrequiredstring | null

What the beneficiary sees (max 20).

actionDaterequiredstring (date-time)

UTC midnight of the payment date.

submittedAtrequiredstring (date-time) | null
paidAtrequiredstring (date-time) | null
failureReasonrequiredstring | null
customerrequiredobject | null
Show fields
customer fields
FieldTypeDescription
idrequiredstring
externalReferencerequiredstring | null
emailrequiredstring
creditNoterequiredobject | null
Show fields
creditNote fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
createdAtrequiredstring (date-time)
updatedAtrequiredstring (date-time)
Example payload
{
  "id": "evt_7f3b15c9e1a5d2b8f4c6e0a3",
  "type": "payout.scheduled",
  "created": "2026-09-27T10:00:00.000Z",
  "data": {
    "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"
  }
}

Payload: customer.payment_method.added, customer.payment_method.removed, customer.payment_method.expiring#

CardWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: customer.payment_method.added, customer.payment_method.removed, customer.payment_method.expiring

createdrequiredstring (date-time)
datarequiredobject
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

customerobject
Show fields
customer fields
FieldTypeDescription
idstring
externalReferencestring | null
Example payload
{
  "id": "evt_7f3b19c9e1a5d2b8f4c6e0a3",
  "type": "customer.payment_method.added",
  "created": "2026-10-05T08:03:00.000Z",
  "data": {
    "object": "card",
    "id": "cmgcard00001visa4242abcd",
    "customerId": "cmg2c0s7t0003cust0001abcd",
    "brand": "visa",
    "last4": "4242",
    "expiryMonth": 12,
    "expiryYear": 2028,
    "holderName": "T NKOSI",
    "isDefault": true,
    "status": "active",
    "expiring": false,
    "source": "card_setup",
    "createdAt": "2026-10-05T08:00:00.000Z",
    "lastUsedAt": null,
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "platform-org:42"
    }
  }
}

Payload: customer.standing.changed#

CustomerStandingWebhookEvent fields
FieldTypeDescription
idrequiredstring

Unique event ID (evt_…).

typerequiredstring

One of: customer.standing.changed

createdrequiredstring (date-time)
datarequiredobject
Show fields
data fields
FieldTypeDescription
objectrequiredstring

One of: customer_standing

customerIdrequiredstring
statusrequiredstring

grace: show a banner. locked: limit the account to billing (sign in, see and pay invoices, add a card).

One of: ok, grace, locked

reasonrequiredstring | null

What locked the account, or what will lock it first.

One of: no_payment_method, unpaid_invoice, null

reasonsrequiredstring[]

One of: no_payment_method, unpaid_invoice

graceEndsAtrequiredstring (date-time) | null
lockedSincerequiredstring (date-time) | null
lockModerequiredstring

One of: billing_only

rulesEnabledrequiredboolean

The standing rules are switched on (Settings → Cards & standing).

rulesApplyFromrequiredstring (date-time) | null

Customers who existed when the rules were switched on: when the rules start to apply to them.

paidPlanrequiredboolean
hasPaymentMethodrequiredboolean

A usable saved card, an active debit order mandate or a gateway card subscription.

paymentMethodsrequiredobject
Show fields
paymentMethods fields
FieldTypeDescription
cardsrequiredinteger

Usable saved cards.

defaultCardrequiredCard | null
Show fields
defaultCard fields
FieldTypeDescription
objectrequiredstring

One of: card

idrequiredstring
customerIdrequiredstring
brandrequiredstring

card when the brand is unknown.

One of: visa, mastercard, amex, diners, card

last4requiredstring
expiryMonthrequiredinteger | null

≥ 1 · ≤ 12

expiryYearrequiredinteger | null
holderNamerequiredstring | null
isDefaultrequiredboolean

The card offered first and charged automatically. At most one per customer.

statusrequiredstring

expired: past its expiry month. failed: the bank rejected the card (e.g. a card token error); add it again.

One of: active, expired, failed, removed

expiringrequiredboolean

Active and expiring within 30 days.

sourcerequiredstring

Saved on the add-card page, or while paying ("save this card").

One of: card_setup, checkout

createdAtrequiredstring (date-time)
lastUsedAtrequiredstring (date-time) | null

Last successful charge.

chargeableboolean

API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable.

debitOrderrequiredboolean
gatewaySubscriptionrequiredboolean
outstandingrequiredobject
Show fields
outstanding fields
FieldTypeDescription
amountrequirednumber
overdueAmountrequirednumber
currencyrequiredstring
invoiceIdsrequiredstring[]
invoicesrequiredobject[]
Show fields
invoices fields
FieldTypeDescription
idrequiredstring
numberrequiredstring
dueDaterequiredstring (date-time)
balancerequirednumber
currencyrequiredstring
overduerequiredboolean
paymentPendingrequiredboolean

A card payment for it is with the bank: it does not count until that payment fails.

awaitingCollectionrequiredboolean

Automatic collection is on and the customer has a default saved card, but saved cards cannot be charged yet (no card debit gateway): the invoice waits for you, not for the customer, so it does not count towards a lock. It counts once a charge was attempted and failed.

linksrequiredobject
Show fields
links fields
FieldTypeDescription
addCardUrlrequiredstring | null

Hosted add-card page for the customer.

payUrlrequiredstring | null

Pay page of the oldest outstanding invoice.

checkedAtrequiredstring (date-time)
changestring

One of: grace_started, locked, unlocked, resolved, reason_changed

previousobject
Show fields
previous fields
FieldTypeDescription
statusstring
reasonstring | null
customerobject
Show fields
customer fields
FieldTypeDescription
idstring
externalReferencestring | null
Example payload
{
  "id": "evt_7f3b19c9e1a5d2b8f4c6e0a3",
  "type": "customer.standing.changed",
  "created": "2026-10-05T08:03:00.000Z",
  "data": {
    "object": "customer_standing",
    "customerId": "cmg2c0s7t0003cust0001abcd",
    "status": "locked",
    "reason": "unpaid_invoice",
    "reasons": [
      "unpaid_invoice"
    ],
    "graceEndsAt": "2026-10-08T07:00:00.000Z",
    "lockedSince": "2026-10-08T07:00:00.000Z",
    "lockMode": "billing_only",
    "rulesEnabled": true,
    "rulesApplyFrom": null,
    "paidPlan": true,
    "hasPaymentMethod": true,
    "paymentMethods": {
      "cards": 1,
      "defaultCard": {
        "object": "card",
        "id": "cmgcard00001visa4242abcd",
        "customerId": "cmg2c0s7t0003cust0001abcd",
        "brand": "visa",
        "last4": "4242",
        "expiryMonth": 12,
        "expiryYear": 2028,
        "holderName": "T NKOSI",
        "isDefault": true,
        "status": "active",
        "expiring": false,
        "source": "card_setup",
        "createdAt": "2026-10-05T08:00:00.000Z",
        "lastUsedAt": null
      },
      "debitOrder": false,
      "gatewaySubscription": false
    },
    "outstanding": {
      "amount": 299,
      "overdueAmount": 299,
      "currency": "ZAR",
      "invoiceIds": [
        "cmg4i5n6v0001inv0001abcd"
      ],
      "invoices": [
        {
          "id": "cmg4i5n6v0001inv0001abcd",
          "number": "INV-000123",
          "dueDate": "2026-10-05T07:00:00.000Z",
          "balance": 299,
          "currency": "ZAR",
          "overdue": true,
          "paymentPending": false,
          "awaitingCollection": false
        }
      ]
    },
    "links": {
      "addCardUrl": null,
      "payUrl": null
    },
    "checkedAt": "2026-10-06T09:00:00.000Z",
    "change": "locked",
    "previous": {
      "status": "grace",
      "reason": "unpaid_invoice"
    },
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "platform-org:42"
    }
  }
}

See the Webhooks guide for setup and signature verification code.