Skip to main content

​
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

ParameterTypeRequiredDescription
bookingIdUUIDYesThe booking ID returned at creation time.

​
Request Body

{
  "paymentReference": "TXN-20260620-99887766"
}
FieldTypeRequiredDescription
paymentReferencestringNoYour internal payment transaction reference (e.g., your payment gateway transaction ID). Stored for reconciliation. Max 255 characters.

​
Example Request

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 
{
  "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 StatusCodeDescription
400VALIDATION_ERRORInvalid path or body parameter
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing partner_bookings_confirm_payment permission
404RESOURCE_NOT_FOUNDBooking not found, or the partner booking reference record is missing
422PAYMENT_RESPONSIBILITY_MISMATCHYour account has paymentResponsibility = CLEANOS; this endpoint is not available to you
422BOOKING_NOT_PAYABLEBooking is canceled or failed — cannot confirm payment
422PAYMENT_ALREADY_CONFIRMEDPayment 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.
  5. Webhook on confirmation. A booking.payment_confirmed webhook event is fired after a successful payment confirmation.

​
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.
  • GET /partners/bookings/:bookingId/status — Check current paymentStatus
  • PATCH /partners/bookings/:bookingId/cancel — Cancel the booking if payment fails