CentraPoint

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.

On this page

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
FieldTypeDescription
referencerequiredstringThe 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",
  "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"
}
Transaction fields
FieldTypeDescription
referencerequiredstringThe payment reference.
statusrequiredstringSee Statuses.
amountrequirednumberGross amount charged, in major units.
feerequirednumber | nullGateway fee, when the gateway reports it (e.g. PayFast).
netrequirednumber | nullAmount after the gateway fee, when reported.
currencyrequiredstringISO 4217 code.
typerequiredstringonce, 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).
gatewayrequiredstringGateway type that processed the payment, e.g. payfast, paystack, mpesa, netcash. See Gateways.
sandboxrequiredbooleantrue 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.
descriptionrequiredstring | nullUsually the payment link title.
providerRefrequiredstring | nullThe gateway's own ID for the payment, useful when talking to the gateway's support.
payerEmailrequiredstring | nullEmail the payer entered at checkout, or reported by the gateway.
paymentLinkIdrequiredstring | nullID of the payment link the payment was made through, if any.
externalReferencerequiredstring | nullThe payment link's (or EFT order's) externalReference, if any. Check it matches the order you are fulfilling.
eftOrderIdrequiredstring | nullThe EFT order this payment belongs to, if any.
metadatarequiredobjectThe payment link's (or EFT order's) metadata; always an object, {} when none.
renewalrequiredbooleantrue for later collections of a subscription.
parentReferencerequiredstring | nullFor renewals: the reference of the subscription's first payment.
subscriptionIdrequiredstring | nullThe subscription started by the payment link, if any.
refundedAmountrequirednumberTotal refunded so far, excluding failed refunds. 0 if none.
refundsrequiredobject[]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.
invoicerequiredobject | 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.
paidAtrequiredstring | nullISO 8601 UTC time the payment became complete.
createdAtrequiredstringISO 8601 UTC time checkout started.

Statuses#

Transaction statuses
statusMeaningFinal?
pendingCheckout started; waiting for the gateway to confirm.No
completePayment received and verified. Safe to fulfil.Yes (unless refunded later)
failedThe gateway declined or the payment could not be started. A later verified success can still move it to complete.Usually
cancelledThe payer cancelled or abandoned checkout. A later verified success can still move it to complete.Usually
refundedThe full amount was refunded (recorded in the dashboard).Yes
partially_refundedPart of the amount was refunded.Yes

Errors#

Transaction lookup errors
StatuserrorWhen
401unauthorizedMissing, malformed, unknown or revoked API key.
403plan_restrictedPlan does not include the REST API.
404not_foundNo transaction with this reference in your organisation.
429rate_limitedMore than 120 requests per minute with this API key. Honour Retry-After.
500internal_errorUnexpected 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.

List transactions#

GET/api/v1/transactions

Lists 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.

List transaction parameters
FieldTypeDescription
statusoptionalstringpending, complete, failed, cancelled, refunded or partially_refunded.
typeoptionalstringonce, recurring or invoice.
customerId, invoiceId, paymentLinkIdoptionalstringFilters.
subscriptionIdoptionalstringPayments of a customer subscription.
from, tooptionalstring (date)YYYY-MM-DD, inclusive, SAST, on the created date.
limit, startingAfteroptionalPagination
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"
List item fields
FieldTypeDescription
id, reference, status, typerequiredstring
amount, fee, net, taxAmount, discountAmountrequirednumber | nullGross amount, gateway fee and net (when known), tax and coupon discount.
currency, gateway, description, providerRefrequiredstring | null
sandboxrequiredbooleanProcessed by a gateway set to sandbox (test) mode; see the lookup response for what it means per gateway.
payerName, payerEmail, customerIdrequiredstring | null
invoicerequiredobject | null{ id, number }
paymentLinkIdrequiredstring | null
subscriptionIdrequiredstring | nullThe 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.)
refundedAmountrequirednumberTotal refunded (excluding failed refunds).
paidAt, createdAtrequiredstring | null
receiptUrlrequiredstring | nullFor completed or refunded payments: the receipt URL.