Payments API

Record, list, retrieve, and update payments against invoices.

Authentication

All payment endpoints require a valid PASETO token:

Authorization: Bearer <token>

Endpoints

Method	Path	Description
POST	/api/payment/:orgId/create	Record a new payment
GET	/api/payment/:orgId/list	List payments (paginated)
GET	/api/payment/:orgId/by-code/:code	Get payment by code
GET	/api/payment/:orgId/:paymentId	Get payment by ID
PUT	/api/payment/:orgId/:paymentId/update	Update a payment

Common Path Parameters

Parameter	Type	Description
orgId	string	Organisation ID
paymentId	string	Payment document ID
code	string	Human-readable payment code (e.g. PAY-0035)

---

POST /api/payment/:orgId/create

Record a new payment.

Request Body

{
  "invoiceId": "inv_pqr456",
  "invoiceCode": "INV-0078",
  "bookingId": "bk_xyz789",
  "guestId": "guest_abc123",
  "guestName": "Jane Smith",
  "amount": 5000,
  "method": "card",
  "cardLast4": "4242",
  "transactionId": "txn_abc123xyz",
  "paymentDate": "2026-03-18",
  "notes": "Partial payment at checkout",
  "receivedBy": "usr_789xyz"
}

Field	Type	Required	Description
invoiceId	string	Yes	Invoice being paid
invoiceCode	string	No	Invoice code for reference
bookingId	string	No	Associated booking ID
guestId	string	No	Guest ID
guestName	string	No	Guest name
amount	number	Yes	Payment amount
method	string	Yes	Payment method (cash, card, upi, bank_transfer, cheque, other)
cardLast4	string	No	Last 4 digits of card (if card)
transactionId	string	No	External transaction reference
paymentDate	string	Yes	Date of payment (YYYY-MM-DD)
notes	string	No	Additional notes
receivedBy	string	No	User ID of staff who received

Response — 201 Created

{
  "success": true,
  "message": "Payment recorded successfully",
  "data": {
    "paymentId": "pay_lmn789",
    "code": "PAY-0035",
    "invoiceId": "inv_pqr456",
    "amount": 5000,
    "method": "card",
    "status": "completed",
    "paymentDate": "2026-03-18",
    "createdAt": "2026-03-18T14:00:00.000Z"
  }
}

Error — 400 Bad Request

{
  "success": false,
  "message": "Payment amount exceeds invoice balance due"
}

---

GET /api/payment/:orgId/list

List payments with pagination and optional filters.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page
method	string	—	Filter by payment method
from	string	—	Payment date from (YYYY-MM-DD)
to	string	—	Payment date to (YYYY-MM-DD)
invoiceId	string	—	Filter by invoice ID
search	string	—	Search by guest name, code, or transaction ID

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "paymentId": "pay_lmn789",
      "code": "PAY-0035",
      "invoiceId": "inv_pqr456",
      "invoiceCode": "INV-0078",
      "guestName": "Jane Smith",
      "amount": 5000,
      "method": "card",
      "status": "completed",
      "paymentDate": "2026-03-18"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 120,
    "totalPages": 6
  }
}

---

GET /api/payment/:orgId/by-code/:code

Retrieve a payment by its human-readable code.

Path Parameters

Parameter	Type	Description
code	string	Payment code (e.g. PAY-0035)

Response — 200 OK

{
  "success": true,
  "data": {
    "paymentId": "pay_lmn789",
    "code": "PAY-0035",
    "invoiceId": "inv_pqr456",
    "invoiceCode": "INV-0078",
    "bookingId": "bk_xyz789",
    "guestId": "guest_abc123",
    "guestName": "Jane Smith",
    "amount": 5000,
    "method": "card",
    "cardLast4": "4242",
    "transactionId": "txn_abc123xyz",
    "status": "completed",
    "paymentDate": "2026-03-18",
    "notes": "Partial payment at checkout",
    "receivedBy": "usr_789xyz",
    "createdAt": "2026-03-18T14:00:00.000Z"
  }
}

Error — 404 Not Found

{
  "success": false,
  "message": "Payment not found"
}

---

GET /api/payment/:orgId/:paymentId

Retrieve full payment details by ID. Response format is identical to the by-code endpoint above.

Response — 200 OK

{
  "success": true,
  "data": {
    "paymentId": "pay_lmn789",
    "code": "PAY-0035",
    "invoiceId": "inv_pqr456",
    "invoiceCode": "INV-0078",
    "bookingId": "bk_xyz789",
    "guestName": "Jane Smith",
    "amount": 5000,
    "method": "card",
    "cardLast4": "4242",
    "transactionId": "txn_abc123xyz",
    "status": "completed",
    "paymentDate": "2026-03-18",
    "notes": "Partial payment at checkout",
    "receivedBy": "usr_789xyz",
    "createdAt": "2026-03-18T14:00:00.000Z",
    "updatedAt": "2026-03-18T14:00:00.000Z"
  }
}

---

PUT /api/payment/:orgId/:paymentId/update

Update an existing payment record.

Request Body

{
  "amount": 5500,
  "method": "upi",
  "transactionId": "upi_ref_987654",
  "notes": "Corrected amount — UPI payment",
  "paymentDate": "2026-03-18"
}

Field	Type	Required	Description
amount	number	No	Updated amount
method	string	No	Updated payment method
transactionId	string	No	Updated transaction reference
notes	string	No	Updated notes
paymentDate	string	No	Updated payment date
cardLast4	string	No	Updated card last 4 digits

Response — 200 OK

{
  "success": true,
  "message": "Payment updated successfully",
  "data": {
    "paymentId": "pay_lmn789",
    "code": "PAY-0035",
    "amount": 5500,
    "method": "upi",
    "updatedAt": "2026-03-19T08:30:00.000Z"
  }
}

Error — 404 Not Found

{
  "success": false,
  "message": "Payment not found"
}