CentraPoint

Getting started

Quickstart

Create an API key in the CentraPoint dashboard and make your first API request.

On this page

This walkthrough takes you from a new API key to a paid invoice: create a customer, invoice them, let them pay through the pay link, and get notified by webhook.

Before you start#

  • A CentraPoint organisation on a plan that includes the REST API (Growth or higher).
  • At least one payment gateway configured and enabled under Settings → Payment providers. Use the gateway's Sandbox mode while testing.
  • An administrator login for the dashboard (only administrators can manage API keys).

New account? Get started walks through sign-up, a sandbox gateway and tax settings in the dashboard. Prefer to click through the API first? Use the Postman collection.

1. Create an API key#

  1. Sign in to the dashboard at app.centrapoint.co.za.
  2. Go to Settings → API keys.
  3. Enter a descriptive name (for example Website checkout – production) and click Create key.
  4. Copy the key immediately. It is shown only once.

The key looks like cp_1a2b3c4d_ followed by a long random secret. The first part (cp_1a2b3c4d) is the key's prefix, which the dashboard shows so you can tell keys apart.

2. Store the key securely#

Keep the key on your server only, for example in an environment variable:

Shell
export CENTRAPOINT_API_KEY="cp_1a2b3c4d_your-secret-here"

3. Create a customer#

Upsert the customer with your own ID as externalReference. Running this again updates the same customer.

curl -X POST "https://app.centrapoint.co.za/api/v1/customers" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7a80" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "CRM-1001",
    "email": "[email protected]",
    "firstName": "Test",
    "lastName": "Customer"
  }'

4. Create and send an invoice#

Create an invoice for that customer. send: true emails it with a pay link; the response includes the same link as payUrl.

curl -X POST "https://app.centrapoint.co.za/api/v1/invoices" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 2c3d4e5f-6071-4829-8b3c-4d5e6f7a8b91" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalReference": "CRM-1001"
    },
    "externalReference": "ORDER-1001",
    "lines": [
      {
        "description": "Test order #1001",
        "quantity": 1,
        "unitPrice": 10
      }
    ],
    "send": true
  }'
201 Created (abridged)
{
  "id": "cmg2i9n0v0005inv0001abcd",
  "number": "INV-000001",
  "status": "sent",
  "externalReference": "ORDER-1001",
  "total": 11.5,
  "amountDue": 11.5,
  "payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc"
}

The total includes your default VAT rate (15% here), added on top of the line prices; send taxInclusive: true if your prices already include tax. Prefer a one-off payment without an invoice? Create a payment link or a checkout session instead; the rest of this guide works the same way.

5. Set up a webhook#

Under Settings → Webhooks, add an HTTPS endpoint on your server, copy the signing secret, and click Send test event. Follow the Webhooks guide to verify signatures. You will receive payment.complete and invoice.paid when the invoice is paid.

Open the payUrl, fill in the payer details, choose a payment method and complete the payment on the gateway's sandbox page. Within moments your endpoint receives the events, for example:

invoice.paid (abridged)
{
  "id": "evt_8b2d4f6a0c1e3a5b7d9f1c2e",
  "type": "invoice.paid",
  "data": {
    "number": "INV-000001",
    "status": "paid",
    "externalReference": "ORDER-1001",
    "amountDue": 0
  }
}

7. Check the invoice#

Webhooks are the primary signal; you can always confirm the state directly:

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

When status is paid, the money has been received and verified. To look up the individual payment, use the reference from the payment.complete webhook (for example CP-20260925-9F3A1C7B) with the Transactions API, and download the receipt with the Receipts API.

Next, read about authentication, error handling and idempotency, then the full payment flow and recurring billing. To bill customers on a schedule, set up packages and plans and subscribe them with the Customer subscriptions API.

Use the Postman collection#

The Postman collection has every endpoint of the API reference, grouped like these docs, with example bodies and saved example responses. It is generated from the same OpenAPI specification, so it always matches the current API version.

Download Postman collection

  1. Download the collection (centrapoint-api.postman_collection.json) with the button above.
  2. Import it in Postman: Import, then drop the file in (or choose it). The collection appears as CentraPoint API. Importing a newer copy later replaces it.
  3. Set your API key: open the collection, go to Variables and paste your key into the Current value of apiKey, then save. Every request sends it as Authorization: Bearer {{apiKey}}. baseUrl is already set to https://app.centrapoint.co.za.
  4. Send a first request: Account → Get your organisation and entitlements (GET /api/v1/me). A 200 with your organisation's name and plan means the key works.

Path variables (such as :id) and bodies hold example values: replace them with ids from your own organisation. Write requests carry a disabled Idempotency-Key header; enable it to make a request safe to retry (see Idempotency).