CentraPoint

Guides

Tax & PDF documents

Configure sales tax such as VAT, how tax-inclusive and exclusive amounts are worked out, document branding, and invoice, receipt, refund and statement PDFs.

On this page

Tax settings#

Set up VAT (or GST, sales tax and so on) under Settings → Tax. You need the tax:write permission to change it; tax:read lets a user view it.

Settings → Tax
SettingRulesUsed for
Charge tax on invoicesOn or offWhen off, the default rate is 0%.
Tax nameRequired, up to 30 characters (e.g. VAT, GST)Labels on documents: the tax column, totals and the registration line.
Rate (%)0 to 100, stored to 2 decimalsDefault rate for new invoice lines.
Prices entered on invoicesExclude tax (tax is added on top) or Include tax (tax is part of the price)The default for dashboard invoices, subscription invoices and hosted checkout.
Tax registration numberOptional, up to 50 charactersPrinted as VAT No: 4123456789 on invoices, receipts, refund notes and statements.

The page shows a live example of a R 100.00 price with your settings, and a Change history of every save (when, who, name, rate, inclusive or exclusive, and registration number). There is one rate per account; invoices can still carry different rates per line through the API (see below).

Before you save tax settings#

Until the Tax page is saved for the first time, CentraPoint uses the VAT rate and VAT number from Settings → Company settings, named "VAT", with prices exclusive of tax (tax is on when the rate is above 0). Saving the Tax page takes over from then on, and keeps those company settings in step.

Reading your tax setting from the API#

GET /api/v1/me returns the setting as it is charged (API 1.17.0), so an integration can check it instead of assuming it. See Get your organisation and entitlements for the whole response.

tax in GET /api/v1/me
{
  "tax": {
    "enabled": false,
    "name": "VAT",
    "rate": 0,
    "inclusive": false,
    "configured": true,
    "taxNumber": null
  }
}
tax fields
FieldMeaning
enabledWhether tax is charged at all: switched on with a rate above 0.
nameThe tax name printed on documents.
rateThe rate that is charged, in percent: 0 when enabled is false, whatever rate is still saved.
inclusivetrue: prices already include tax. false: tax is added on top.
configuredfalse: the Tax page was never saved, so the company VAT rate above applies, added on top. An account that must charge no tax should save the Tax page with tax off, so this reads true with enabled: false.
taxNumberThe tax registration number printed on your documents, or null.

How tax is calculated#

Tax is worked out per invoice line, then added up. Amounts are rounded to 2 decimals (half up) at each step:

  1. Line amount = round2(quantity × unitPrice).
  2. Line rate = the line's own taxRate if given, else the default rate.
  3. Line tax:
    • exclusive: round2(amount × rate / 100)
    • inclusive: round2(amount × rate / (100 + rate))
  4. Tax = sum of line taxes. Gross = sum of line amounts.
    • exclusive: subtotal = gross; total = round2(subtotal + tax)
    • inclusive: subtotal (net) = round2(gross − tax); total = gross

The invoice's headline taxRate is the rate of the line with the largest amount. Lines with an empty description or a quantity of 0 are dropped, unit prices cannot be negative, and the total must be greater than zero.

Worked example#

Two lines at a default rate of 15%: 3 × R 33.33 (standard rate) and 1 × R 10.00 with taxRate: 0 (zero-rated).

Exclusive versus inclusive, same lines
Exclusive (tax on top)Inclusive (tax in the price)
Line 1 amount3 × 33.33 = 99.993 × 33.33 = 99.99
Line 1 taxround2(99.99 × 15 / 100) = round2(14.9985) = 15.00round2(99.99 × 15 / 115) = round2(13.0422) = 13.04
Line 2 amount / tax10.00 / 0.0010.00 / 0.00
Subtotal109.99109.99 − 13.04 = 96.95
Tax15.0013.04
Total124.99109.99
Headline taxRate15 (line 1 is the largest)15

Where the default applies#

Tax defaults by source
Invoice created byRateInclusive or exclusive
Dashboard (Invoices → New)The default rate for every line when Apply tax is ticked, else 0%Prices include tax is pre-ticked from your setting; you can change it per invoice
POST /api/v1/invoicesPer-line taxRate, else the default ratetaxInclusive in the request; defaults to false, whatever your setting
Subscription billingThe default rateFollows your setting. With inclusive prices the net unit price is chosen so the invoice total equals the plan price exactly

taxInclusive on the Invoices API#

When you create an invoice with POST /api/v1/invoices, tax follows these rules:

  • taxInclusive (boolean, optional) says whether your line prices already include tax. It defaults to false: tax is added on top. Your tenant's inclusive or exclusive setting is not used by the API.
  • lines[].taxRate (0–100, optional) sets a line's rate and always wins over the default.
  • Lines without taxRate use your tenant default: the Tax settings rate when tax is on, 0 when it is off (or the legacy company VAT rate if the Tax page was never saved).
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 5b0e7c1a-3d2f-4e8b-9a6c-1f4d2e7b8c90" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalReference": "CRM-1001"
    },
    "taxInclusive": true,
    "lines": [
      {
        "description": "Hosting (3 months)",
        "quantity": 3,
        "unitPrice": 33.33
      },
      {
        "description": "Zero-rated item",
        "quantity": 1,
        "unitPrice": 10,
        "taxRate": 0
      }
    ]
  }'

With a 15% default this gives the inclusive column of the worked example: subtotal 96.95, tax 13.04, total 109.99. The same request without taxInclusive gives the exclusive column: total 124.99.

Branding on documents#

On plans with Custom branding, Settings → Branding controls how PDFs, payment pages, the customer portal and emails look. It shows a live preview of an invoice and the payment page.

Settings → Branding
SettingRulesWhere it shows
LogoPNG, JPEG or WebP, up to 2 MB, no SVG. A wide image around 600 × 150 px works best.Top of every PDF (PNG and JPEG only; WebP logos are not shown on PDFs), payment pages, portal. Without a logo the company name is shown.
IconSquare, at least 256 × 256 px, same formatsCompact places such as checkout headers and the portal browser tab.
Display nameUp to 150 characters, optionalReplaces your company name on documents and payment pages.
Primary colourHex, e.g. #0f5fbfAccents on PDFs, buttons on payment pages and emails.
Secondary colourHex, optionalSecondary accents on PDFs.
PDF font size80% to 130%Text size on PDFs.
PDF templateModern, Classic or MinimalModern: accent bands and a filled table header. Classic: double rules and a dark table header. Minimal: thin lines and lots of white space.
PDF footerUp to 1000 charactersBottom of every PDF page, e.g. registration and banking details.
Payment termsUp to 2000 charactersInvoices and statements.
NotesUp to 2000 charactersReceipts, and invoices that have no notes of their own.

Without custom branding, documents use the Modern template, a dark slate colour (#0f172a), your company name instead of a logo, and no footer, payment terms or notes. Company address, email, phone and company registration number come from Settings → Company settings, and the tax registration line from Settings → Tax.

Default terms#

Settings → Company settings holds the terms your new invoices, quotes and credit notes start with. They are your own terms to your customers, and you can change them there or on each document. CentraPoint's default wording covers when and how to pay, late payment, questions, your refund and cancellation policy (which it points to, without promising anything for you), and, on quotes, how long the quote is valid, what is included, how to accept and the 7-day ECTA cooling-off for consumers who accept online. Leave a box empty to go back to the default. Invoices created through the API without notes use your invoice terms. Each line written as Label: text prints with the label in bold.

PDF documents#

Four branded A4 documents are generated on demand from live data:

Invoice#

  • Title: PRO FORMA INVOICE for pro forma invoices, TAX INVOICE when the invoice has tax and you have a tax registration number, otherwise INVOICE. The dashboard's printable invoice page uses the same title.
  • Invoice number, issue and due dates, the customer's account code and status (paid, overdue and so on).
  • Billing period: 1 Oct 2026 - 31 Oct 2026 under the header when the invoice has a billing period (see Billing periods and line details). Quotes and credit notes show theirs the same way.
  • Bill-to block with the customer's name, billing email, address and their VAT number if set.
  • Lines with quantity, unit price and amount, plus a tax-rate column when the invoice has tax. Each line's details are printed under its description, with the line's own period when it differs from the invoice's. Invoices that mix rates list the tax per rate ("VAT @ 15% on …").
  • Subtotal ("Subtotal (excl. VAT)" on inclusive invoices), tax, total, and paid and balance due once something is paid. Inclusive invoices add "Prices include VAT."
  • Payment terms, and notes (the invoice's notes, else your branding notes). Long notes wrap and continue on the next page, above the footer. Pro forma invoices add that they are a request for payment in advance and not a tax invoice; subscription invoices add that the subscription renews as agreed until it ends or is cancelled, and whom to contact to change or stop it.

Receipt#

PAYMENT RECEIPT for a payment that completed (also after a full or partial refund). The receipt number is the payment reference. It shows the date paid, payment method, related invoice, who paid, the amount (with any coupon discount), and the tax contained in the payment: the payment's own tax amount, else the invoice's tax share of this payment, else, for a direct sale with tax-inclusive settings, the tax in the amount. Refunds against the payment are listed, followed by your branding notes.

Refund note#

REFUND NOTE with the refund number, date, original payment reference and date, invoice, amount, the tax refunded (in proportion to the refunded share of the payment), reason and refund method.

Statement#

STATEMENT of a customer's account in one currency for a period: opening balance, then invoices (debits), payments against them, both online and recorded offline (credits), and refunds (debits), with a running and closing balance, the amounts still owed by age on the last day (not yet due, 1-30, 31-60, 61-90 and over 90 days past the due date), and your payment terms. Dates are South African days. The default period is the last 90 days, the maximum is 5 years, and the currency defaults to that of the customer's latest invoice. Drafts and cancelled invoices are left out.

Getting the PDFs#

Where to download each document
DocumentDashboardCustomer portalPayerAPI
InvoiceInvoice page → Download PDF (Print opens a printable page)Invoices → PDF (issued invoices only)Attached to the invoice emailGET /api/v1/invoices/{id}/pdf
ReceiptTransaction page → Download receiptPayments → ReceiptDownload receipt link after paying; attached to the receipt emailGET /api/v1/receipts/{id}?format=pdf
Refund noteTransaction page → refunds → PDF--GET /api/v1/refunds/{id}?format=pdf
StatementCustomer page → statement (choose dates)Statement → Download PDF--

The payer's receipt link appears on the payment result page once a payment is complete. It is a signed link, so a payment ID or reference alone cannot be used to fetch someone else's receipt. See Customer portal for portal access.

PDF API endpoints#

All three need an API key on a plan with the REST API and return the PDF as a download: Content-Type: application/pdf, Content-Disposition: attachment; filename="…" and Cache-Control: private, no-store. Errors are JSON in the usual error format.

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

The invoice PDF by invoice ID. Requires the Invoicing plan feature (403 plan_restricted otherwise). 404 when the invoice is not found. File name: Invoice-INV-000123.pdf.

GET/api/v1/receipts/{id}?format=pdf

The receipt PDF, looked up by transaction ID or payment reference. Only payments that are complete, partially refunded or refunded have receipts (404 otherwise). Without format=pdf the endpoint returns the receipt as JSON (see Receipts & refunds). File name: Receipt-CP-20260925-9F3A1C7B.pdf.

GET/api/v1/refunds/{id}?format=pdf

The refund note PDF, looked up by refund ID or refund number (404 when not found). Without format=pdf it returns the refund as JSON. File name: Refund-RF-000012.pdf.

Download PDFs with cURL
# Invoice
curl -f -o invoice.pdf "https://app.centrapoint.co.za/api/v1/invoices/cmg2c0s7t0009inv0001abcd/pdf" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

# Receipt, by payment reference
curl -f -o receipt.pdf "https://app.centrapoint.co.za/api/v1/receipts/CP-20260925-9F3A1C7B?format=pdf" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

# Refund note, by refund number
curl -f -o refund.pdf "https://app.centrapoint.co.za/api/v1/refunds/RF-000012?format=pdf" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

PDFs in emails#

The invoice email attaches the invoice PDF, and the receipt email attaches the receipt PDF. Receipt emails are sent once per completed payment when Email customers a receipt when a payment completes is on under Settings → Company settings. If a PDF cannot be generated, the email is still sent without it. Resending an email from the email log does not include attachments. See Email & templates.