API

Transactions API

Look up a payment's status and refunds with GET /api/v1/transactions/{reference}; polling as a fallback to webhooks.

On this page

Get a transaction
Response
Statuses
Errors
Code samples
Polling guidance

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#

GET/api/v1/transactions/{reference}

Path parameters
Field	Type	Description
`reference`required	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.

200 OK

{
  "reference": "CP-20260925-9F3A1C7B",
  "status": "partially_refunded",
  "amount": 499,
  "fee": 14.47,
  "net": 484.53,
  "currency": "ZAR",
  "type": "invoice",
  "gateway": "payfast",
  "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"
}

Transaction fields
Field	Type	Description
`reference`required	string	The payment reference.
`status`required	string	See Statuses.
`amount`required	number	Gross amount charged, in major units.
`fee`required	number \| null	Gateway fee, when the gateway reports it (e.g. PayFast).
`net`required	number \| null	Amount after the gateway fee, when reported.
`currency`required	string	ISO 4217 code.
`type`required	string	`once`, `recurring` (subscription payments and renewals), `invoice` (payments for an invoice), `debit_order` (Netcash debit order collections) or `eft` (EFT orders).
`gateway`required	string	Gateway type that processed the payment, e.g. `payfast`, `paystack`, `mpesa`, `netcash`. See Gateways.
`description`required	string \| null	Usually the payment link title.
`providerRef`required	string \| null	The gateway's own ID for the payment, useful when talking to the gateway's support.
`payerEmail`required	string \| null	Email the payer entered at checkout, or reported by the gateway.
`paymentLinkId`required	string \| null	ID of the payment link the payment was made through, if any.
`externalReference`required	string \| null	The payment link's (or EFT order's) `externalReference`, if any. Check it matches the order you are fulfilling.
`eftOrderId`required	string \| null	The EFT order this payment belongs to, if any.
`metadata`required	object	The payment link's (or EFT order's) metadata; always an object, `{}` when none.
`renewal`required	boolean	`true` for later collections of a subscription.
`parentReference`required	string \| null	For renewals: the reference of the subscription's first payment.
`subscriptionId`required	string \| null	The subscription started by the payment link, if any.
`refundedAmount`required	number	Total refunded so far, excluding failed refunds. 0 if none.
`refunds`required	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.
`invoice`required	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`.
`paidAt`required	string \| null	ISO 8601 UTC time the payment became complete.
`createdAt`required	string	ISO 8601 UTC time checkout started.

Statuses#

Transaction 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#

Transaction lookup 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 pending transaction 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, refunded or partially_refunded.
Remember the rate limit of 120 requests per minute per API key across all your polling, and watch the X-RateLimit-Remaining header.