# Bank & Surcharge Rate APIs – Financial Department

APIs for managing banks and surcharge rates, and for querying booking transactions with bank/surcharge details (which bank, rate used at creation, and real bank charges from the surcharge table).

**Base path:** All under `auth:sanctum` (authenticated).

---

## 1. Banks

### 1.1 List Banks

**GET** `/api/banks`

| Query   | Type    | Description                    |
|---------|---------|--------------------------------|
| `active_only` | boolean | If `1`, return only active banks. |

**Response:** `data` = array of bank objects:

```json
{
  "status": "success",
  "message": "Banks retrieved successfully.",
  "data": [
    { "id": 1, "name": "台新", "name_en": "Taishin", "sort_order": 1, "is_active": true, "created_at": "...", "updated_at": "..." }
  ]
}
```

### 1.2 Show Bank

**GET** `/api/banks/{bank}`

Returns one bank with `surcharge_rates` loaded.

### 1.3 Create Bank

**POST** `/api/banks`

| Body          | Type    | Required | Description        |
|---------------|---------|----------|--------------------|
| `name`        | string  | yes      | Bank name (e.g. 台新) |
| `name_en`     | string  | no       | English name       |
| `sort_order`  | integer | no       | Display order      |
| `is_active`   | boolean | no       | Default `true`     |

### 1.4 Update Bank

**PUT/PATCH** `/api/banks/{bank}`

Same fields as create (all optional).

### 1.5 Delete Bank

**DELETE** `/api/banks/{bank}`

Deletes the bank. Surcharge rates for this bank are cascade-deleted.

---

## 2. Surcharge Rates

### 2.1 List Surcharge Rates

**GET** `/api/surcharge-rates`

| Query              | Type    | Description                                  |
|--------------------|---------|----------------------------------------------|
| `terminal_type`    | string  | e.g. 實體刷卡機, 線上刷卡機                    |
| `bank_id`          | integer | Bank ID                                      |
| `payment_category` | string  | 國内, 國外, 銀聯                              |
| `active_only`      | boolean | If `1`, only active rates                    |

**Response:** `data` = array of surcharge rate objects (each includes `bank` with `id`, `name`, `name_en`).

### 2.2 Rate Table (for lookup)

**GET** `/api/surcharge-rates/table`

Returns the same structure as in the financial-summary meta: `terminal_type → bank_name → [ { payment_category, installment_periods, rate } ]`. Use for dropdowns and surcharge calculation.

**Response example:**

```json
{
  "status": "success",
  "message": "Surcharge rate table retrieved successfully.",
  "data": {
    "實體刷卡機": {
      "台新": [
        { "payment_category": "國内", "installment_periods": null, "rate": 1.66 },
        { "payment_category": "國外", "installment_periods": null, "rate": 3.2 }
      ]
    }
  }
}
```

### 2.3 Terminal Types

**GET** `/api/surcharge-rates/terminal-types`

**Response:** `data` = array of strings, e.g. `["實體刷卡機", "線上刷卡機"]`.

### 2.4 Show Surcharge Rate

**GET** `/api/surcharge-rates/{surcharge_rate}`

Single rate with `bank` loaded.

### 2.5 Create Surcharge Rate

**POST** `/api/surcharge-rates`

| Body                   | Type    | Required | Description                          |
|------------------------|---------|----------|--------------------------------------|
| `terminal_type`        | string  | yes      | 實體刷卡機 or 線上刷卡機               |
| `bank_id`              | integer | yes      | Bank ID                              |
| `payment_category`      | string  | yes      | 國内, 國外, 銀聯                      |
| `installment_periods`   | integer | no       | `null` = 未分期, or 3, 6, 12, etc.   |
| `rate`                 | number  | yes      | Rate % (e.g. 1.5)                    |
| `is_active`            | boolean | no       | Default `true`                       |

### 2.6 Update / Delete Surcharge Rate

**PUT/PATCH** `/api/surcharge-rates/{surcharge_rate}`  
**DELETE** `/api/surcharge-rates/{surcharge_rate}`

---

## 3. Transaction Surcharge Report (financial department)

Lets the financial department see, for card payments: which bank was used, what surcharge rate was applied when the transaction was created, the surcharge amount charged, and the **real** bank charge based on the current surcharge table (for comparison).

**GET** `/api/financial/transaction-surcharge-report`

**Filters:**

| Query        | Type   | Description                                      |
|-------------|--------|--------------------------------------------------|
| `booking_id` | integer | Only transactions for this booking              |
| `date_from`  | date   | Transactions on or after this date (Y-m-d)      |
| `date_to`    | date   | Transactions on or before this date (Y-m-d)      |
| `bank`       | string | Bank name (e.g. 台新)                             |
| `per_page`   | integer| Results per page (default 50, max 100)           |

**Response:** Paginated list of **main** payment transactions only (國內/國外信用卡 with `bank` set). Surcharge transactions (payment_type = surcharge) are excluded — they are just the fee to cover bank charges; the report shows the main transaction (deposit, balance, full, etc.) and its surcharge details. Each item includes:

| Field                    | Type    | Description |
|--------------------------|---------|-------------|
| `transaction_id`         | integer | Booking transaction ID |
| `booking_id`             | integer | Booking ID |
| `booking_number`         | string  | Booking number |
| `payment_date`           | string  | Y-m-d |
| `payment_type`           | string  | deposit, balance, full, etc. |
| `payment_method`         | string  | 國內信用卡 / 國外信用卡 |
| `amount`                 | number  | Payment amount |
| `bank`                   | string  | Bank name used |
| `terminal_type`          | string  | 實體刷卡機 / 線上刷卡機 |
| `installment_periods`    | int/null| 未分期 = null |
| `traveler_id` / `traveler_name` | | Traveler (if any) |
| `surcharge_charged`      | number  | Surcharge amount actually charged (from booking_charges) |
| `rate_used_at_creation`  | number/null | Rate % used when the transaction was created (from charge record) |
| `reference_amount`       | number  | Amount the surcharge was applied to |
| `bank_rate_from_table`   | number/null | Current rate % from surcharge_rates table (lookup by bank, terminal, category, installment) |
| `bank_charge_by_table`   | number/null | What the bank charge would be at current table rate: `reference_amount * bank_rate_from_table / 100` |
| `difference`             | number/null | `surcharge_charged - bank_charge_by_table` (positive = we charged more than current table; negative = we charged less) |

**Example:**

```json
{
  "status": "success",
  "message": "Transaction surcharge report retrieved successfully.",
  "data": {
    "transactions": {
      "current_page": 1,
      "data": [
        {
          "transaction_id": 101,
          "booking_id": 5,
          "booking_number": "B2025-001",
          "payment_date": "2025-03-01",
          "payment_type": "balance",
          "payment_method": "國外信用卡",
          "amount": 40000,
          "bank": "台新",
          "terminal_type": "線上刷卡機",
          "installment_periods": null,
          "traveler_id": 12,
          "traveler_name": "王小明",
          "surcharge_charged": 600,
          "rate_used_at_creation": 1.5,
          "reference_amount": 40000,
          "bank_rate_from_table": 3.2,
          "bank_charge_by_table": 1280,
          "difference": -680
        }
      ],
      "per_page": 50,
      "total": 1
    },
    "meta": {
      "filters": { "date_from": "2025-01-01", "date_to": "2025-12-31" }
    }
  }
}
```

Use this report to:

- See which bank and rate was used for each card transaction.
- Compare what was charged (`surcharge_charged`) vs what the current surcharge table implies (`bank_charge_by_table`).
- Use `difference` to spot over/under charges relative to the current table.