ChatBedsนักพัฒนา
Hotel features API

หน้านี้ยังไม่ได้แปล คุณจึงกำลังอ่านฉบับภาษาอังกฤษ

Payments in WhatsApp and phone bookings

Choose what a guest pays when Ana books a room on WhatsApp or a phone call, an advance with a Pay now button or pay at the hotel, and how the 2-hour hold, the reminder and the release work.

When Ana books a room for a guest on WhatsApp or on a phone call, the hotel chooses what the guest pays at that moment:

modeWhat the guest pays when booking
FOLLOWThe booking page's way (the default). If the booking page requires a card, the hotel's deposit rule, or everything when there is no rule. Otherwise nothing: paid at the hotel
HOTELNothing. Paid at the hotel
ADVANCEAn advance in the chat: a percent of the total (100, 50, any percent) or the first night

With ADVANCE, a rate plan's own deposit rule wins, and a non-refundable rate is always paid in full. A private offer the guest agreed to pay now (see Negotiation) is always paid in full.

If the hotel can't take cards (Stripe isn't connected, or the plan has no card payments), the booking is paid at the hotel. It is never refused for that. The one exception is a pay-now offer: Ana can't book it, and says so.

What the guest sees

  1. Before the guest says yes, Ana reads back the total, what is paid now and what is left.
  2. The booking is made and the room is held for 2 hours. The confirmation in the chat has a Pay now button, never a link in the text.
  3. After 1 hour unpaid, the guest gets one reminder with the Pay now button again.
  4. Paid: the guest gets a receipt, then the full booking confirmation (dates and times, guests, extras, what is paid and left, cancellation terms, address, a View booking button).
  5. After 2 hours unpaid, the booking is cancelled with no fee and the guest is told, with a Book again button.

A booking with nothing to pay now gets the full confirmation straight away. Bookings already made keep what they were asked when the setting changes.

On your side, these are ordinary bookings and payments: a payment.completed webhook when the advance is paid, and reservation.cancelled when an unpaid booking is let go.

Get the setting

GET/api/v1/finance/chat-payment
Permission: finance.view or settings.manage

Parameters

property_id uuid (query)required
The property.

Example

Request
curl "https://app.chatbeds.app/api/v1/finance/chat-payment?property_id=6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
200 OK
{
  "property_id": "6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b",
  "mode": "ADVANCE",
  "kind": "PERCENT",
  "value": 50.0,
  "balance_days": 7,
  "hold_hours": 2,
  "remind_after_hours": 1,
  "cards_ready": true
}
FieldMeaning
modeFOLLOW, HOTEL or ADVANCE
kindWith ADVANCE: PERCENT or FIRST_NIGHT. Otherwise null
valueWith PERCENT: the percent of the total. Otherwise null
balance_daysDays before arrival the rest is due. null: the rest is paid at check-in
hold_hoursHow long the room is held for the advance. Always 2
remind_after_hoursWhen the unpaid guest is reminded. Always 1
cards_readytrue when the hotel can take cards now (Stripe connected and on the plan). When false, every chat booking is paid at the hotel

Change the setting

PUT/api/v1/finance/chat-payment
Permission: settings.manage

Body

property_id uuidrequired
The property.
mode stringrequired
FOLLOW, HOTEL or ADVANCE.
kind string
Required with ADVANCE: PERCENT or FIRST_NIGHT. Ignored otherwise.
value number
With PERCENT: more than 0 and at most 100.
balance_days integer
0 to 365: days before arrival the rest is due. Leave it out for the rest at check-in.

Example

Request
curl -X PUT "https://app.chatbeds.app/api/v1/finance/chat-payment" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b", "mode": "ADVANCE", "kind": "PERCENT", "value": 50, "balance_days": 7}'

The answer is the setting, as for GET. With FOLLOW or HOTEL, kind, value and balance_days come back null.

Errors

StatusdetailWhen
400The advance is a percent of the total or the first night.ADVANCE without a valid kind
400Type the deposit's percent or amount.PERCENT without a value
403The role lacks settings.manage
404Property not found
422mode or kind not one of the values above, value not above 0 or over 100, balance_days out of range

The Pay now button

GET/public/v1/pay/{token}
No authentication. The guest's own address.

The Pay now button opens this address on ChatBeds, never Stripe's page directly. So a button tapped late still does the right thing:

  • Something is owed now: a 303 redirect to the Stripe card page for that amount. The open page is reused when it is for the same amount; otherwise it is closed and a new one made (for example after an extra was added).
  • Nothing can be paid (already paid, the 2 hours passed, the booking cancelled, too little time left to open a new page): a 303 redirect to the guest's booking page (/stay?t={token}), which says why.

token is the booking's stay token, the one in the guest's booking page address. Calls are limited per address; too many answer 429.

กำลังสร้างอะไรอยู่หรือเปล่า?

ในหน้านี้