Payments

Payments are money received from customers or paid to vendors, allocated against one or more transactions.

Payment types (paymentHeader.paymentType): CustomerPayment, VendorPayment, SalesReturnAllocation, PurchaseReturnAllocation.

Record a payment

POST /txndata/upsertPayment — Permission: CustomerPayment · Write or VendorPayment · Write — multipart/form-data

Form field	Type	Notes
paymentDto	string (JSON)	Required. A Payment object serialised to a JSON string.
file	file	Optional attachment.

Response 200:

{ "message": "Transaction Saved!" }

Validation rules (each violation returns 400):

• paymentHeader.totalAmt must equal paymentAmt + discountAmt + withHoldingAmt + otherChargesAmt.
• paymentHeader.paymentAcct (the bank or cash account) is required for CustomerPayment and VendorPayment.
• The sum of paymentLines[].allocAmt cannot exceed totalAmt.
• Each line's allocAmt cannot exceed what is actually still due on that transaction — the server checks the live balance, not the dueAmt you send.
• You cannot pay a cancelled transaction.
• A payment linked to a bank transaction cannot have its amount, date or account changed.
• The payment date cannot be in a locked financial year.

Example: customer payment against the invoice above

curl -X POST "$BASE_URL/txndata/upsertPayment" \
  -H "x-api-key: YOUR_API_KEY" \
  -F 'paymentDto={
  "paymentHeader": {
    "paymentId": "a1b2c3d4-0000-4000-8000-00000000abcd",
    "paymentType": "CustomerPayment",
    "paymentNo": "PMT-0007",
    "paymentDate": "2026-09-26",
    "contactId": "c3b1f0e2-6a52-4c1a-9d0e-2f6b9a7d1e10",
    "contactName": "Acme Traders",
    "paymentAmt": 1180,
    "totalAmt": 1180,
    "paymentAcct": "BANK_ACCOUNT_ID",
    "paymentMode": "Bank Transfer"
  },
  "paymentLines": [
    {
      "txnId": "5d0c9a7e-3b1f-4a52-8c64-0e9f2b7a1c88",
      "txnNo": "INV-0042",
      "totalAmt": 1180,
      "dueAmt": 1180,
      "allocAmt": 1180
    }
  ]
}'

Read payments

Endpoint	Permission	Description
GET /txndata/getPayments/{paymentType}	CustomerPayment · Read or VendorPayment · Read	Query dateFilter (JSON, required). Returns Payment[], or 204.
GET /txndata/getPayment/{paymentId}	CustomerPayment · Read or VendorPayment · Read	One Payment, or 404.
GET /txndata/getPaymentsByTxnId/{txnId}	any role	All payments allocated to a transaction, or 204.
GET /txndata/getPaymentsByReturnId/{returnTxnId}	any role	All payments/allocations for a return transaction, or 204.
GET /txndata/getReturnPayment/{returnTxnId}	Read on a transaction type	The refund payment for a return transaction, or 404.
GET /txndata/getPaymentView/{paymentId}	CustomerPayment · Read or VendorPayment · Read	The payment receipt rendered as an HTML string.

Delete payments

Endpoint	Permission	Description
DELETE /txndata/deletePayment/{paymentId}	CustomerPayment · Full or VendorPayment · Full	Returns { "message": "Delete Success!" }.
DELETE /txndata/bulkDeletePayment	CustomerPayment · Full or VendorPayment · Full	Body: { "paymentIds": ["id1","id2"] }. Same response shape as bulkDeleteTxn.

Send a payment receipt

POST /txndata/sendPayment — Permission: CustomerPayment · Write or VendorPayment · Write. Emails a payment receipt to up to 3 recipients. Body and limits are the same as sendTxn (including the required htmlContent); rate-limited to 3 per 10 minutes.

---

Data model

Only the commonly used properties are listed. Unless marked required, every property is optional. Properties that the server sets itself (bizId, createdBy, modifiedBy, app, and creation/modification timestamps) should be left out of requests. The OpenAPI document has the complete definitions.

Payment

{
  "paymentHeader": { },
  "paymentLines": [ ]
}

paymentHeader

Property	Type	Notes
paymentId	string	Required. Caller-generated unique ID.
paymentType	string	CustomerPayment, VendorPayment, SalesReturnAllocation, PurchaseReturnAllocation.
paymentNo	string	Your receipt/payment number.
paymentDate	date
contactId, contactName	string
paymentAmt	number	Money actually paid.
discountAmt, withHoldingAmt, otherChargesAmt	number
totalAmt	number	Must equal paymentAmt + discountAmt + withHoldingAmt + otherChargesAmt.
paymentAcct	string	Required for customer and vendor payments. The bank or cash account ID.
paymentMode	string	For example Cash, Bank Transfer, Cheque.
currencyId, fxRateAmt	string, number
reference, notes	string
isAdvancePayment	boolean	An unallocated advance from the contact.
returnTxnId, cashRefundAcct, cashRefundAmt	mixed	For refunds against returns.
tags	string[]

paymentLines[]

Property	Type	Notes
txnId	string	The transaction being paid.
txnNo, txnDate	string, date	For display.
totalAmt	number	The transaction's total.
dueAmt	number	Balance due when you read it.
allocAmt	number	Amount of this payment applied to the transaction.
discountAmt	number	Settlement discount on this line.
deleteFlag	boolean	true to remove the allocation when updating.