> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/payments.md).

# 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

```http
GET /api/v1/client/payments
```

#### Query Parameters

* `bid` (optional): Filter payments by Booking UUID.

#### Example Request

```bash
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)

```json
[
  {
    "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

```http
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](/api-documentation/guests/get.md)) 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`

```bash
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)

```json
{
  "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

```http
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`

```bash
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

```http
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.