CentraPoint

API

Receipts & refunds API

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

On this page

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
EndpointPurpose
GET /api/v1/receiptsList receipts
GET /api/v1/receipts/{id}Get a receipt by transaction ID or payment reference; ?format=pdf for the PDF
POST /api/v1/refundsRecord a refund of a completed payment
GET /api/v1/refundsList 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, GET /api/v1/invoices, quotes, credit notes and payouts) 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
FieldTypeDescription
idrequiredstringTransaction ID.
receiptNumber, referencerequiredstringThe payment reference (the receipt number is the reference).
statusrequiredstringcomplete, partially_refunded or refunded.
amount, currencyrequirednumber, stringAmount paid.
taxAmountrequirednumber | nullTax included in the payment, when known (from the payment or its invoice).
discountAmountrequirednumber | nullCoupon discount, if any.
refundedAmountrequirednumberTotal refunded (excluding failed refunds).
description, payerName, payerEmail, customerIdrequiredstring | null
paymentMethod, gatewayrequiredstringDisplay name of the payment method and gateway type, e.g. payfast.
invoicerequiredobject | null{ id, number, externalReference } when the payment was for an invoice.
paidAt, createdAtrequiredstring
pdfUrlrequiredstringRelative URL of the receipt PDF (call it with your API key).

List receipts#

GET/api/v1/receipts
List receipt parameters
FieldTypeDescription
customerIdoptionalstringFilter by customer.
invoiceIdoptionalstringFilter by invoice.
from, tooptionalstring (date)Payment date range.
limit, startingAfteroptionalPagination

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
FieldTypeDescription
id, refundNumberrequiredstringRefund ID and number (REF-…).
amount, currencyrequirednumber, string
statusrequiredstringpending, processed or failed.
reasonrequiredstring | null
providerRefrequiredstring | nullThe gateway's refund ID.
customerIdrequiredstring | null
transactionrequiredobject{ id, reference, invoiceId } of the refunded payment.
processedAt, createdAtrequiredstring | null, string
pdfUrlrequiredstringRelative URL of the refund note PDF.

List refunds#

GET/api/v1/refunds
List refund parameters
FieldTypeDescription
statusoptionalstringpending, processed or failed.
customerIdoptionalstringFilter by customer.
transactionReferenceoptionalstringRefunds of the payment with this reference.
from, tooptionalstring (date)Range on the date the refund was recorded.
limit, startingAfteroptionalPagination
curl -X GET "https://app.centrapoint.co.za/api/v1/refunds?transactionReference=CP-20260925-9F3A1C7B" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Record a refund#

POST/api/v1/refunds
FieldTypeDescription
transactionReferencerequiredstringReference of a complete or partially refunded payment.
amountrequirednumberAmount to refund (up to what is still refundable).
reasonoptionalstringShown on the refund note.
providerRefoptionalstringThe gateway's refund id, if you already refunded in the gateway portal.

Returns the refund object (201). The payment becomes refunded or partially_refunded, any invoice balance is updated and payment.refunded / payment.partially_refunded is sent. Refunds are recorded in CentraPoint; return the money in your gateway's portal. Send an Idempotency-Key header so retries never refund twice.

curl -X POST "https://app.centrapoint.co.za/api/v1/refunds" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionReference": "CP-20260925-9F3A1C7B",
    "amount": 150,
    "reason": "Cancelled order"
  }'

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
StatuserrorWhen
400invalid_requestInvalid status, date not YYYY-MM-DD, or unknown startingAfter.
403plan_restrictedAPI access is not included in your plan.
404not_foundNo receipt/refund with this ID or number in your organisation.
401 / 429 / 500unauthorized / rate_limited / internal_errorSee Errors