Payments

Manage standalone payment records for your property. Payments can be optionally linked to a Booking (bid) or a Guest (gid).

Amount format: Payment amounts use decimal strings (e.g., "150.00"), not integers. This is different from the Bookings API, where amounts are integers in minor units (e.g., 15000 = 150.00). Sending an integer to the Payments API will result in a validation error.

---

List Payments

Retrieve a list of payment records for the property.

Endpoint

GET /api/v1/client/payments

Query Parameters

• bid (optional): Filter payments by Booking UUID.

Example Request

curl "https://api.hostelmate.co/api/v1/client/payments?bid=e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json"

Example Response (200 OK)

[
  {
    "id": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
    "bid": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
    "gid": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
    "amount": "260.0000",
    "paymentMethod": "POS",
    "type": "income",
    "description": "Room upgrade fee",
    "name": "Front Desk Payment",
    "date": "2025-10-02T11:00:00Z",
    "status": true
  }
]

status: true means the payment is active. status: false means it has been soft-deleted and is hidden from standard views.

---

Create Payment

Log a new payment or expense.

Endpoint

POST /api/v1/client/payments

Request Payload

Field	Type	Description
amount	string	Required. Decimal string (e.g., "260.00"). Do not use integers or minor units.
paymentMethod	string	Required. One of: Cash, Bank Transfer, Credit Card, POS, OTA.
type	string	Required. One of: income, outgoing.
bid	string	Optional. Booking UUID to link this payment to a booking.
gid	string	Optional. Guest UUID (guestId from the Guests API) to link to a guest without a booking.
name	string	Optional. Display name for the record (default: "Client API Payment").
description	string	Optional. Internal notes.

Example curl

curl "https://api.hostelmate.co/api/v1/client/payments" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "amount": "150.00",
    "paymentMethod": "Cash",
    "type": "income",
    "bid": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
    "description": "Deposit for extra night"
  }'

Idempotency-Key is required on this endpoint. Omitting it returns 400 bad_request.

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "bid": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "gid": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
  "amount": "150.0000",
  "paymentMethod": "Cash",
  "type": "income",
  "description": "Deposit for extra night",
  "name": "Client API Payment",
  "date": "2025-10-02T11:00:00Z",
  "status": true
}

---

Update Payment

Modify an existing payment record.

Endpoint

PATCH /api/v1/client/payments/{paymentId}

This is a partial update — only include the fields you want to change. Idempotency-Key is required.

Example curl

curl "https://api.hostelmate.co/api/v1/client/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -X PATCH \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "amount": "200.00",
    "description": "Updated description"
  }'

---

Delete Payment (Soft Delete)

Deactivate a payment record.

Endpoint

DELETE /api/v1/client/payments/{paymentId}

Response

• 204 No Content: Soft delete successful.

• 404 Not Found: Payment does not exist.

Soft Delete: This sets the payment status to false. The record is hidden from standard views but is retained in the database for financial auditing purposes.