CentraPoint

API

Subscriptions API

List, retrieve, pause, resume and cancel gateway-managed card subscriptions started by recurring payment links.

On this page

Overview#

A subscription is created when a payer completes a recurring payment link. The gateway (PayFast or Netcash Pay Now) then charges the card automatically on each cycle; every collection appears as a new transaction with renewal: true. Use this API to look subscriptions up and to pause, resume or cancel them. Changes are also pushed as subscription webhooks (subscription.activated, .charged, .payment_failed, .paused, .resumed, .cancelled). See the Recurring billing guide for the full picture.

The subscription object#

Subscription
{
  "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"
}
Subscription fields
FieldTypeDescription
idrequiredstringSubscription ID (also returned as subscriptionId on transactions and webhooks).
statusrequiredstringactive, paused or cancelled.
frequencyrequiredstring | nullmonthly, quarterly, biannually or annually.
amountrequirednumber | nullAmount of each collection.
currencyrequiredstringCurrency of the payment link.
gatewayrequiredstringE.g. payfast, netcash_paynow.
paymentLinkIdrequiredstring | nullThe recurring link that started it.
externalReferencerequiredstring | nullThat link's externalReference.
metadatarequiredobjectThat link's metadata.
createdAt, updatedAtrequiredstring

List subscriptions#

GET/api/v1/subscriptions
List query parameters
FieldTypeDescription
externalReferenceoptionalstringThe payment link's externalReference.
limitoptionalinteger1–100, default 20.
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions?externalReference=SUB-ACME-PRO" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a subscription#

GET/api/v1/subscriptions/{id}
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Pause, resume and cancel rules#

Subscription actions
ActionAllowed fromResultWebhookGateways
pauseactivepausedsubscription.pausedThose that support pausing: PayFast, Netcash Pay Now
resumepausedactivesubscription.resumedThose that support pausing: PayFast, Netcash Pay Now
cancelactive or pausedcancelledsubscription.cancelledPayFast, Netcash Pay Now
  • CentraPoint asks the gateway first and only changes the status when the gateway accepts. If it refuses, you get 502 gateway_error and nothing changes.
  • Repeats are safe: calling an action that has already taken effect (pause when paused, resume when active, cancel when cancelled) returns 200 with the subscription unchanged and sends no webhook. These endpoints don't use the Idempotency-Key header.
  • Invalid transitions return 409 invalid_state, e.g. pausing or resuming a cancelled subscription.
  • Unsupported actions return 409 unsupported: on a gateway that can only cancel, pausing or resuming is refused before anything is sent to the gateway (and the dashboard hides its Pause button); capabilities on the subscription says which actions its gateway supports. Netcash Pay Now pauses and resumes at the gateway (Subscription Update Service) since 23 October 2026; a date that passed while paused moves forward on the same schedule. The status checks above come first, so a repeat still returns 200 and an invalid transition 409 invalid_state.
  • The same actions in the dashboard send the same webhooks.

Pause a subscription#

POST/api/v1/subscriptions/{id}/pause

Stops collections until resumed. Returns the subscription with status: "paused". No body is needed.

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

Restarts collections for a paused subscription. Returns it with status: "active". No body is needed.

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

Asks the gateway to stop future collections, then marks the subscription cancelled, sends the subscription.cancelled webhook and returns it. No body is needed. Allowed from active or paused; cancelling an already cancelled subscription returns it unchanged. Payments already collected are not refunded.

curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/cancel" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Errors#

Subscription errors
StatuserrorWhen
404not_foundNo subscription with this ID in your organisation.
409invalid_stateThe action isn't allowed from the current status (e.g. resume a cancelled subscription). Nothing changed.
409unsupportedThe subscription's gateway can't do this action, e.g. pause or resume on a gateway that can only cancel (see capabilities). Nothing changed.
409invoice_linkedUpdate, replace or retry with another amount on a subscription started by a recurring link for an invoice: every payment is invoiced with the invoice's lines, so the amount is fixed. Nothing changed.
409nothing_to_retryRetry when no missed charge (failed renewal or charged retry of this subscription) is left to re-collect - each was re-collected, or its charged retry is still pending - and no amount was sent. An invoice-linked subscription returns it whenever no missed charge is left to re-collect, with or without amount. A subscription that is not invoice-linked and never missed a charge is collected now instead (and, with amount, one whose missed charges were all re-collected). Nothing changed.
502gateway_errorThe gateway rejected or failed the request. Nothing changed; retry later.
403plan_restricted / account_restrictedNo API access, or the account is read-only (actions).
401 / 429 / 500unauthorized / rate_limited / internal_errorSee Errors