Payments and folios

There are four ways to settle an order. Pick the one that matches how the money
is collected.

Pay in full

POST /pos/orders/{order_id}/pay
X-Staff-Token: <staff token>

{ "method": "card", "amount": "29.70", "tip": "4.00" }

method is one of cash, card, room_charge, house_account or comp. The
order becomes paid immediately.

For a room charge, the order must carry the guest's reservation_id; set it when
creating or updating the order. For a house account, send house_account_id.

Take several payments

Splitting a bill evenly, or letting each guest pay what they owe, does not need
separate orders. Capture each payment against the same order:

POST /pos/orders/{order_id}/payments/

{ "method": "cash", "amount": "15.00", "tip_amount": "2.00" }

When the captured amounts, tips included, reach the order total, the order
becomes paid. After that, further captures are refused.

Don't call /pay on an order that already has captured payments. It records
the full total again, on top of what was captured. Capture the remainder with /payments/ instead.

GET /pos/orders/{order_id}/payments/ lists what has been captured.
POST /pos/orders/{order_id}/payments/{payment_id}/refund refunds part or all of
a payment as a new negative payment linked to the original.

Tips

POST /pos/orders/{order_id}/tip sets the tip as a preset percentage, a custom
percentage of the pre-tax subtotal, or a fixed amount. With payment_id the tip
is recorded on that payment. Without it, the tip is recorded on the order and
collected when the order is paid.

Where a paid order lands in Cloudbeds

A paid order is posted to Cloudbeds as a POS check, with its items, taxes,
fees, discounts, service charge and gratuity:

The order response reports the outcome:

folio_error carries a code and message when the status is failed or
rejected.

A failed posting never undoes the payment. The guest has paid, and the order
stays paid. Retry with POST /pos/orders/{order_id}/folio/retry, optionally
choosing a different house_account_id. Postings are idempotent per order, so
an order already on the folio is never posted twice.

Charge to room from a POS provider

When a property connects a third-party POS such as Clover, its terminals ring up
orders in the provider's system. To put such an order on a guest's bill:

1. Find the target. GET /pos/charge-targets?type=reservation&query=smith
   returns reservations, or groups with type=group. Targets that cannot be
   charged come back with blocked: true and a blockedReason.

2. Charge it. Send the provider's order as it is, with the target:

   HTTP

   POST /pos/charges
   Idempotency-Key: 6f2d1c9e-0b7a-4e3f-9a51-2c8d7e4b0f13
   
   {
     "orderId": "CLV-8Q2W4E6R",
     "order": { "...": "the order exactly as the provider returned it" },
     "folioTargetType": "reservation",
     "folioTargetId": "8812345"
   }

3. Add a gratuity later, if the guest tips after the charge:
   POST /pos/charges/{order_id}/gratuities.

4. Void it to correct a mistake: DELETE /pos/charges/{order_id} reverses the
   check, its gratuities and its payments. Then charge again with a new
   Idempotency-Key.

Idempotency-Key is required. A retry with the same key returns the original
result. The same key with a different payload returns 409.

The terminal's merchant must be connected to the property, or the request returns
403 with integration_disconnected.