Quickstart

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).

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:

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
  }'

{
  "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). Prefer a one-off payment without an invoice? Create a payment link 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.

6. Pay in sandbox#

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:

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

Next, read about authentication, error handling and idempotency, then the full payment flow and recurring billing.