# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostelmate.co/api-documentation/payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.