Payments

Process payments and save manual transactions. Requires the payments:direct scope. Supported currencies: NZD (New Zealand Dollar) and AUD (Australian Dollar).

POST/api/v1/{system}/payNow🔒 payments:direct

Process a payment through a terminal's configured gateway. Tenant ownership is validated server-side. Optionally attach an itemised basket via lineItems — when present it is reconciled against the merchandise total and rejected with HTTP 400 (ERR_LINE_ITEM_MISMATCH / ERR_INVALID_LINE_ITEMS) if it is out of balance or malformed.

Auth: Bearer JWT

Request Body

Field	Type	Required	Description
grandTotal	string	Yes	Decimal string, dot separator, 2 places, range 0.01–999999.99 (e.g. "10.00"). Not minor-unit integer cents.
referenceId	string	Yes	Unique transaction reference (must be unique per merchant). This is the identifier a later refund resolves against — always send your own order id.
branchId	long	Yes	Branch user ID
configId	long	Yes	Terminal config ID (from listTerminals)
channel	string	No	Send the UPPERCASE enum name: WECHAT, ALIPAY, UNION_PAY, CENTRA_PAY (case-insensitive and camelCase aliases are also accepted, but UPPERCASE is canonical).
authCode	string	No	QR scan code (required when qrMode=false)
qrMode	boolean	No	true = generate QR for customer to scan
tipAmount	string	No	Decimal string. Tip portion of grandTotal — declare it so an itemised basket reconciles (grandTotal includes the tip; a basket is merchandise only).
feeAmount / donationAmount / discount	string	No	Decimal strings. Other modifier portions of grandTotal, used (with tipAmount) to compute the expected merchandise total for lineItems reconciliation.
lineItems	LineItem[]	No	Optional itemised basket (max 200 lines). Each line: name (<=255), quantity (decimal string, weight-capable e.g. "1.25"), unitPriceCents (int cents), lineTotalCents (int cents, tax-inclusive, after line discount), taxCents? (int), sku? (<=128), category? (<=128). Reconciliation (strict, ±1c): sum(lineTotalCents) must equal grandTotal − tip − fee − donation + discount (converted to cents). NOTE amounts here are integer cents, unlike the decimal-string grandTotal.

Response Example

{
  "status": true,
  "paymentStatus": "SUCCESS",
  "referenceId": "REF-001",
  "tradeNo": "TRADE-123",
  "grandTotal": "10.00",
  "channel": "WECHAT",
  "currency": "NZD"
}

⚠️ Live testing disabled for this endpoint — it modifies data. Use curl or the SDK against your sandbox.

POST/api/v1/{system}/saveTransaction🔒 payments:direct

Save a manually recorded transaction (e.g. cash or external payment).

Auth: Bearer JWT

Request Body

Field	Type	Required	Description
grandTotal	string	Yes	Decimal amount
referenceId	string	Yes	Unique reference
branchId	long	Yes	Branch user ID
configId	long	Yes	Terminal config ID
channel	string	Yes	Payment channel (e.g. CASH)

⚠️ Live testing disabled for this endpoint — it modifies data. Use curl or the SDK against your sandbox.