Subscriptions API

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#

{
  "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"
}

List subscriptions#

curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions?externalReference=SUB-ACME-PRO" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a subscription#

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

Pause, resume and cancel rules#

• 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: Netcash Pay Now subscriptions can only be cancelled, so pausing or resuming one is refused before anything is sent to the gateway (and the dashboard hides its Pause button). 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#

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#

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#

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#