API
Transactions API
List payments, and look up a payment's status and refunds with GET /api/v1/transactions/{reference}; polling as a fallback to webhooks.
Use this endpoint to confirm the outcome of a payment on your server before you fulfil an order. It is the authoritative view of the payment: statuses only change after CentraPoint has verified the gateway's notification.
Get a transaction#
/api/v1/transactions/{reference}| Field | Type | Description |
|---|---|---|
referencerequired | string | The payment reference, e.g. CP-20260925-9F3A1C7B. URL-encode it if you build the path yourself. Find the references for your order with GET /api/v1/payment-links?externalReference=. See Idempotency, metadata & references. |
Only transactions in the API key's organisation are visible. Works on read-only accounts.
Response#
200 OK. All fields are always present; optional values are null.
{
"reference": "CP-20260925-9F3A1C7B",
"status": "partially_refunded",
"amount": 499,
"fee": 14.47,
"net": 484.53,
"currency": "ZAR",
"type": "invoice",
"gateway": "payfast",
"sandbox": false,
"description": "Website hosting - October",
"providerRef": "2458761",
"payerEmail": "[email protected]",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "ORDER-1001",
"eftOrderId": null,
"metadata": {
"cartId": "c_8841"
},
"renewal": false,
"parentReference": null,
"subscriptionId": null,
"refundedAmount": 100,
"refunds": [
{
"refundNumber": "REF-7C21A9F0",
"amount": 100,
"currency": "ZAR",
"status": "processed",
"processedAt": "2026-09-26T09:30:00.000Z",
"createdAt": "2026-09-26T09:29:41.000Z"
}
],
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"invoiceNumber": "INV-000042",
"status": "paid",
"externalReference": "ORDER-1001"
},
"paidAt": "2026-09-25T08:14:03.512Z",
"createdAt": "2026-09-25T08:12:47.020Z"
}| Field | Type | Description |
|---|---|---|
referencerequired | string | The payment reference. |
statusrequired | string | See Statuses. |
amountrequired | number | Gross amount charged, in major units. |
feerequired | number | null | Gateway fee, when the gateway reports it (e.g. PayFast). |
netrequired | number | null | Amount after the gateway fee, when reported. |
currencyrequired | string | ISO 4217 code. |
typerequired | string | once, recurring (subscription payments and renewals), invoice (payments for an invoice), debit_order (Netcash debit order collections), eft (EFT orders), card_setup (the R1.00 payment that saves a card) or card_debit (a saved card charged by the bank; pending until the bank confirms). |
gatewayrequired | string | Gateway type that processed the payment, e.g. payfast, paystack, mpesa, netcash. See Gateways. |
sandboxrequired | boolean | true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives. |
descriptionrequired | string | null | Usually the payment link title. |
providerRefrequired | string | null | The gateway's own ID for the payment, useful when talking to the gateway's support. |
payerEmailrequired | string | null | Email the payer entered at checkout, or reported by the gateway. |
paymentLinkIdrequired | string | null | ID of the payment link the payment was made through, if any. |
externalReferencerequired | string | null | The payment link's (or EFT order's) externalReference, if any. Check it matches the order you are fulfilling. |
eftOrderIdrequired | string | null | The EFT order this payment belongs to, if any. |
metadatarequired | object | The payment link's (or EFT order's) metadata; always an object, {} when none. |
renewalrequired | boolean | true for later collections of a subscription. |
parentReferencerequired | string | null | For renewals: the reference of the subscription's first payment. |
subscriptionIdrequired | string | null | The subscription started by the payment link, if any. |
refundedAmountrequired | number | Total refunded so far, excluding failed refunds. 0 if none. |
refundsrequired | object[] | Refunds recorded for the payment, oldest first (failed refunds excluded): refundNumber (e.g. REF-7C21A9F0), amount, currency, status (pending or processed), processedAt, createdAt. Empty array if none. |
invoicerequired | object | null | { id, number, invoiceNumber, status, externalReference } when the payment is for an invoice (invoiceNumber equals number and is kept for compatibility). Invoice status is one of draft, sent, paid, overdue, cancelled. |
paidAtrequired | string | null | ISO 8601 UTC time the payment became complete. |
createdAtrequired | string | ISO 8601 UTC time checkout started. |
Statuses#
| status | Meaning | Final? |
|---|---|---|
pending | Checkout started; waiting for the gateway to confirm. | No |
complete | Payment received and verified. Safe to fulfil. | Yes (unless refunded later) |
failed | The gateway declined or the payment could not be started. A later verified success can still move it to complete. | Usually |
cancelled | The payer cancelled or abandoned checkout. A later verified success can still move it to complete. | Usually |
refunded | The full amount was refunded (recorded in the dashboard). | Yes |
partially_refunded | Part of the amount was refunded. | Yes |
Errors#
| Status | error | When |
|---|---|---|
| 401 | unauthorized | Missing, malformed, unknown or revoked API key. |
| 403 | plan_restricted | Plan does not include the REST API. |
| 404 | not_found | No transaction with this reference in your organisation. |
| 429 | rate_limited | More than 120 requests per minute with this API key. Honour Retry-After. |
| 500 | internal_error | Unexpected server error. Retry with backoff. |
Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/transactions/CP-20260925-9F3A1C7B" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Polling guidance#
Prefer webhooks to learn about status changes as they happen. Use polling as a fallback, for example for payments you have not received an event for, or to confirm an event before acting on it.
- Most gateways confirm within seconds; mobile-money payments wait for the payer to approve on their phone and can take minutes.
- Poll a
pendingtransaction no more than every 5–10 seconds while a customer is waiting, then back off (for example every few minutes) for up to a day. - Stop polling once the status is
complete,refundedorpartially_refunded. - Remember the rate limit of 120 requests per minute per API key across all your polling, and watch the
X-RateLimit-Remainingheader.
List transactions#
/api/v1/transactionsLists payments in your organisation, newest first, with keyset pagination (limit 1–100, default 20; startingAfter = the previous page's nextCursor). The response is { "data": [ … ], "hasMore": …, "nextCursor": … }. Each item is a summary; fetch GET /api/v1/transactions/{reference} for the full detail and refunds.
| Field | Type | Description |
|---|---|---|
statusoptional | string | pending, complete, failed, cancelled, refunded or partially_refunded. |
typeoptional | string | once, recurring or invoice. |
customerId, invoiceId, paymentLinkIdoptional | string | Filters. |
subscriptionIdoptional | string | Payments of a customer subscription. |
from, tooptional | string (date) | YYYY-MM-DD, inclusive, SAST, on the created date. |
limit, startingAfteroptional | Pagination |
curl -X GET "https://app.centrapoint.co.za/api/v1/transactions?status=complete&from=2026-09-01&to=2026-09-30&limit=50" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"| Field | Type | Description |
|---|---|---|
id, reference, status, typerequired | string | |
amount, fee, net, taxAmount, discountAmountrequired | number | null | Gross amount, gateway fee and net (when known), tax and coupon discount. |
currency, gateway, description, providerRefrequired | string | null | |
sandboxrequired | boolean | Processed by a gateway set to sandbox (test) mode; see the lookup response for what it means per gateway. |
payerName, payerEmail, customerIdrequired | string | null | |
invoicerequired | object | null | { id, number } |
paymentLinkIdrequired | string | null | |
subscriptionIdrequired | string | null | The customer subscription the payment belongs to. (In GET /api/v1/transactions/{reference} and payment.* webhooks, subscriptionId is the gateway subscription started by a recurring link.) |
refundedAmountrequired | number | Total refunded (excluding failed refunds). |
paidAt, createdAtrequired | string | null | |
receiptUrlrequired | string | null | For completed or refunded payments: the receipt URL. |