API

Receipts & refunds API

List and retrieve receipts for completed payments and refunds, as JSON or as branded PDF documents.

On this page

Overview
Pagination and date filters
The receipt object
List receipts
Get a receipt
The refund object
List refunds
Get a refund
PDF downloads
Errors

Overview#

A receipt is a payment that completed: a transaction with status complete, partially_refunded or refunded. A refund is money returned against such a payment. Both are available as JSON and as the same branded PDF documents your customers get (see Tax & PDF documents). These endpoints need only the REST API in your plan.

Receipt and refund endpoints
Endpoint	Purpose
`GET /api/v1/receipts`	List receipts
`GET /api/v1/receipts/{id}`	Get a receipt by transaction ID or payment reference; ?format=pdf for the PDF
`GET /api/v1/refunds`	List refunds
`GET /api/v1/refunds/{id}`	Get a refund by ID or refund number; ?format=pdf for the refund note

Pagination and date filters#

These lists (and GET /api/v1/transactions) use keyset pagination and return:

List response

{
  "data": [
    "…"
  ],
  "hasMore": true,
  "nextCursor": "cmg2t1x2y0009txn0001abcd"
}

limit: 1–100, default 20.
startingAfter: pass the previous page's nextCursor (the last item's id) to get the next page. nextCursor is null on the last page. An ID that isn't in the (filtered) list returns 400.
from / to: YYYY-MM-DD, inclusive, in South African time (SAST). Other formats return 400.

The receipt object#

Receipt

{
  "id": "cmg2t1x2y0009txn0001abcd",
  "object": "receipt",
  "receiptNumber": "CP-20260925-9F3A1C7B",
  "reference": "CP-20260925-9F3A1C7B",
  "status": "complete",
  "amount": 1150,
  "currency": "ZAR",
  "taxAmount": 150,
  "discountAmount": null,
  "refundedAmount": 0,
  "description": "Invoice INV-00042",
  "payerName": "Thandi Nkosi",
  "payerEmail": "[email protected]",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "paymentMethod": "PayFast",
  "gateway": "payfast",
  "invoice": {
    "id": "cmg2i4n5v0004inv0001abcd",
    "number": "INV-00042",
    "externalReference": "ORD-5531"
  },
  "paidAt": "2026-09-25T08:14:03.000Z",
  "createdAt": "2026-09-25T08:12:40.000Z",
  "pdfUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd?format=pdf"
}

Receipt fields
Field	Type	Description
`id`required	string	Transaction ID.
`receiptNumber, reference`required	string	The payment reference (the receipt number is the reference).
`status`required	string	`complete`, `partially_refunded` or `refunded`.
`amount, currency`required	number, string	Amount paid.
`taxAmount`required	number \| null	Tax included in the payment, when known (from the payment or its invoice).
`discountAmount`required	number \| null	Coupon discount, if any.
`refundedAmount`required	number	Total refunded (excluding failed refunds).
`description, payerName, payerEmail, customerId`required	string \| null
`paymentMethod, gateway`required	string	Display name of the payment method and gateway type, e.g. `payfast`.
`invoice`required	object \| null	`{ id, number, externalReference }` when the payment was for an invoice.
`paidAt, createdAt`required	string
`pdfUrl`required	string	Relative URL of the receipt PDF (call it with your API key).

List receipts#

GET/api/v1/receipts

List receipt parameters
Field	Type	Description
`customerId`optional	string	Filter by customer.
`invoiceId`optional	string	Filter by invoice.
`from, to`optional	string (date)	Payment date range.
`limit, startingAfter`optional		Pagination

Newest payment first.

curl -X GET "https://app.centrapoint.co.za/api/v1/receipts?customerId=cmg2c0s7t0003cust0001abcd&from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a receipt#

GET/api/v1/receipts/{id}

id is the transaction ID or the payment reference (CP-…). A payment that isn't complete (or refunded) has no receipt and returns 404.

curl -X GET "https://app.centrapoint.co.za/api/v1/receipts/CP-20260925-9F3A1C7B" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

The refund object#

Refund

{
  "id": "cmg4f5e6d0008rfd0001abcd",
  "object": "refund",
  "refundNumber": "REF-7C21A9F0",
  "amount": 200,
  "currency": "ZAR",
  "status": "processed",
  "reason": "Duplicate charge",
  "providerRef": "1234567",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "transaction": {
    "id": "cmg2t1x2y0009txn0001abcd",
    "reference": "CP-20260925-9F3A1C7B",
    "invoiceId": "cmg2i4n5v0004inv0001abcd"
  },
  "processedAt": "2026-09-26T09:00:00.000Z",
  "createdAt": "2026-09-26T08:58:00.000Z",
  "pdfUrl": "/api/v1/refunds/cmg4f5e6d0008rfd0001abcd?format=pdf"
}

Refund fields
Field	Type	Description
`id, refundNumber`required	string	Refund ID and number (`REF-…`).
`amount, currency`required	number, string
`status`required	string	`pending`, `processed` or `failed`.
`reason`required	string \| null
`providerRef`required	string \| null	The gateway's refund ID.
`customerId`required	string \| null
`transaction`required	object	`{ id, reference, invoiceId }` of the refunded payment.
`processedAt, createdAt`required	string \| null, string
`pdfUrl`required	string	Relative URL of the refund note PDF.

List refunds#

GET/api/v1/refunds

List refund parameters
Field	Type	Description
`status`optional	string	`pending`, `processed` or `failed`.
`customerId`optional	string	Filter by customer.
`transactionReference`optional	string	Refunds of the payment with this reference.
`from, to`optional	string (date)	Range on the date the refund was recorded.
`limit, startingAfter`optional		Pagination

curl -X GET "https://app.centrapoint.co.za/api/v1/refunds?transactionReference=CP-20260925-9F3A1C7B" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a refund#

GET/api/v1/refunds/{id}

id is the refund ID or refund number.

PDF downloads#

Add ?format=pdf to GET /api/v1/receipts/{id} or GET /api/v1/refunds/{id} (or use pdfUrl) to get the document instead of JSON. Invoices have their own endpoint, GET /api/v1/invoices/{id}/pdf. The response is application/pdf with Content-Disposition: attachment and Cache-Control: private, no-store.

Download a receipt PDF

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

Errors#

Receipt and refund errors
Status	error	When
400	`invalid_request`	Invalid status, date not YYYY-MM-DD, or unknown startingAfter.
403	`plan_restricted`	API access is not included in your plan.
404	`not_found`	No receipt/refund with this ID or number in your organisation.
401 / 429 / 500	`unauthorized` / `rate_limited` / `internal_error`	See Errors