> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecleanlife.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm Payment

> POST /partners/bookings/:id/confirm-payment — Confirm payment.

## Overview

Marks a booking's payment as confirmed by the partner. This endpoint is **only available to partners with `paymentResponsibility = PARTNER`**.

When your partner account has `PARTNER` payment responsibility, your system is responsible for collecting payment from your customer. After successful payment collection on your side, call this endpoint to notify CleanLife that the booking has been paid. This transitions the booking's `paymentStatus` from `PENDING` to `PAID`.

***

## Endpoint

```
POST /partners/bookings/:bookingId/confirm-payment
```

## Authentication

Requires a valid API Key with the `partner_bookings_confirm_payment` permission.

***

## Path Parameters

| Parameter   | Type | Required | Description                               |
| ----------- | ---- | -------- | ----------------------------------------- |
| `bookingId` | UUID | **Yes**  | The booking ID returned at creation time. |

***

## Request Body

```json theme={null}
{
  "paymentReference": "TXN-20260620-99887766"
}
```

| Field              | Type   | Required | Description                                                                                                                             |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentReference` | string | No       | Your internal payment transaction reference (e.g., your payment gateway transaction ID). Stored for reconciliation. Max 255 characters. |

***

## Example Request

```bash theme={null}
curl -X POST "https://apiv3.thecleanlife.dev/v1/partners/bookings/11111111-0000-0000-0000-000000000001/confirm-payment" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentReference": "TXN-20260620-99887766"
  }'
```

***

## Success Response

**HTTP Status:** `200 OK`

```json theme={null}
{
  "success": true,
  "data": {
    "bookingId": "11111111-0000-0000-0000-000000000001",
    "externalReference": "ORDER-20260615-001",
    "appointmentId": "22222222-0000-0000-0000-000000000002",
    "status": "in progress",
    "paymentStatus": "PAID",
    "trackingReference": "SA-0042",
    "date": "2026-06-20T00:00:00.000Z",
    "timeslot": {
      "startAt": "09:00",
      "endAt": "12:00",
      "endsAtNextDay": false
    },
    "appointment": {
      "id": "22222222-0000-0000-0000-000000000002",
      "name": "SA-0042",
      "status": "Scheduled",
      "scheduledStartDateTime": "2026-06-20T09:00:00+03:00",
      "scheduledEndDateTime": "2026-06-20T12:00:00+03:00"
    }
  }
}
```

***

## Error Responses

| HTTP Status | Code                              | Description                                                                               |
| ----------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
| `400`       | `VALIDATION_ERROR`                | Invalid path or body parameter                                                            |
| `401`       | `UNAUTHORIZED`                    | Missing or invalid API key                                                                |
| `403`       | `FORBIDDEN`                       | Missing `partner_bookings_confirm_payment` permission                                     |
| `404`       | `RESOURCE_NOT_FOUND`              | Booking not found, or the partner booking reference record is missing                     |
| `422`       | `PAYMENT_RESPONSIBILITY_MISMATCH` | Your account has `paymentResponsibility = CLEANOS`; this endpoint is not available to you |
| `422`       | `BOOKING_NOT_PAYABLE`             | Booking is `canceled` or `failed` — cannot confirm payment                                |
| `422`       | `PAYMENT_ALREADY_CONFIRMED`       | Payment for this booking was already confirmed                                            |

***

## Business Rules

1. **PARTNER responsibility only.** This endpoint is exclusively for partners configured with `paymentResponsibility = PARTNER`. If your account has `CLEANOS` responsibility, calling this endpoint returns `422 PAYMENT_RESPONSIBILITY_MISMATCH`.

2. **Cannot confirm payment for cancelled or failed bookings.** If the booking is in `canceled` or `failed` status, payment confirmation is rejected.

3. **Duplicate confirmation.** Calling this endpoint again after payment is already confirmed returns `422 PAYMENT_ALREADY_CONFIRMED`. Treat this as a successful no-op.

4. **Payment reference stored for reconciliation.** The `paymentReference` you provide is stored with a confirmation timestamp for billing reconciliation between CleanLife and your organization.

***

## Notes

* Even if you do not have an external payment reference (e.g., for invoiced arrangements), you can call this endpoint with an empty body (`{}`) to confirm that payment has been arranged.
* The `paymentStatus` in subsequent `GET /partners/bookings/:bookingId/status` responses will reflect `PAID` after this call.

***

## Related Endpoints

* `GET /partners/bookings/:bookingId/status` — Check current `paymentStatus`
* `PATCH /partners/bookings/:bookingId/cancel` — Cancel the booking if payment fails