Эта страница ещё не переведена, поэтому вы читаете английскую версию.
Folios and payments
Read a booking's bill, post charges, record payments you took, send or void a card payment link on the hotel's Stripe account, check a payment's status, and handle refunds.
Every reservation has a folio: the guest's bill. Room nights, extras, fees and tax go on it as charges when the booking is made; payments go on it as they are received. balance is what is still owed.
Bookings made through the API are pay at the hotel. If your app takes the money, record it with folio.addPayment; if the hotel should take it by card, send the guest a payment link. The Take payments guide walks through both.
Get the folio
/reservations/{reservation_id}/foliofolios:readOperation folio.getReturns every line on the bill (voided lines included and marked), the totals, the balance and the payments.
Parameters
Example
curl -X GET "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/folio" \
-H "Authorization: Bearer cbk_••••"{
"folio": {
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"currency": "USD",
"lines": [
{
"id": "bdaead22-6697-49a1-ad00-510f88b151cc",
"type": "ROOM_CHARGE",
"description": "Standard, night of 2026-10-31",
"amount": 90.0,
"service_date": "2026-10-31",
"posted_at": "2026-10-10T05:09:47.274835",
"voided": false,
"void_reason": null,
"payment_id": null
},
{
"id": "7df0796f-3e3e-48ff-8361-eeeff715f7b4",
"type": "ROOM_CHARGE",
"description": "Standard, night of 2026-11-01",
"amount": 90.0,
"service_date": "2026-11-01",
"posted_at": "2026-10-10T05:09:47.277372",
"voided": false,
"void_reason": null,
"payment_id": null
},
{
"id": "442f2691-f69f-4da3-bfc6-de650d9a9866",
"type": "INCIDENTAL",
"description": "Airport transfer",
"amount": 35.0,
"service_date": "2026-10-10",
"posted_at": "2026-10-10T05:09:47.387569",
"voided": false,
"void_reason": null,
"payment_id": null
},
{
"id": "d3dc1f18-4b15-42b5-bf9f-a3b375b3435e",
"type": "PAYMENT",
"description": "Paid through Sandbox key",
"amount": 100.0,
"service_date": null,
"posted_at": "2026-10-10T05:09:47.406626",
"voided": false,
"void_reason": null,
"payment_id": "763300e8-3898-4fba-a0b0-0a0cc86ba611"
}
],
"total_charges": 215.0,
"total_payments": 100.0,
"balance": 115.0,
"payments": [
{
"id": "763300e8-3898-4fba-a0b0-0a0cc86ba611",
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"kind": "PAYMENT",
"amount": 100.0,
"currency": "USD",
"method": "CARD",
"status": "COMPLETED",
"reference": "BK-PAY-88231",
"paid_at": "2026-10-10T05:09:47.406608+00:00",
"created_at": "2026-10-10T05:09:47.405620+00:00",
"url": null,
"expires_at": null
}
]
}
}| Field | Meaning |
|---|---|
lines[].type | ROOM_CHARGE (one per night), INCIDENTAL (extras and charges), FEE, TAX, PAYMENT, REFUND |
lines[].service_date | The night or day the charge is for; null for payments |
lines[].voided | true when the hotel took the line off the bill; void_reason says why. Voided lines do not count in the totals |
lines[].complimentary | true when the line was given free (by the hotel or an app): it stays on the bill at its price, voided too, and void_reason starts with Complimentary: and says why. See Give a charge free |
lines[].payment_id | On PAYMENT and REFUND lines, the payment it records |
total_charges | All charges not voided |
total_payments | Payments received, less refunds |
balance | total_charges minus total_payments. Negative means the hotel owes the guest money |
payments[] | Every payment, including links not yet paid |
windows[] | The bill's windows when the hotel splits it between payers (a company, another guest, an OTA virtual card): number, label, payer (GUEST, OTHER_GUEST, COMPANY, AGENT, OTA_CARD), charges, payments, balance. One window, the guest's, when the bill isn't split |
lines[].windows | A charge's amount in each window, like {"1": 20.0, "2": 180.0} |
payments[].window | The window a payment pays |
Errors
| Status | detail | When |
|---|---|---|
403 | The app token lacks folios:read | |
404 | Reservation not found |
Add a charge
/reservations/{reservation_id}/folio/chargesfolios:writeOperation folio.addChargePuts something the guest had on the bill: a transfer, a meal, a tour you sold. The line is amount times quantity, dated today at the hotel, and tax is recalculated. Returns the whole folio.
Body
Airport transfer.1. Above 1 the line reads Airport transfer x2.Example
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/folio/charges" \
-H "Authorization: Bearer cbk_••••" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: BK-104233-charge-transfer" \
-d '{"description": "Airport transfer", "amount": 35, "quantity": 1}'{
"folio": {
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"currency": "USD",
"lines": [
{
"id": "bdaead22-6697-49a1-ad00-510f88b151cc",
"type": "ROOM_CHARGE",
"description": "Standard, night of 2026-10-31",
"amount": 90.0,
"service_date": "2026-10-31",
"posted_at": "2026-10-10T05:09:47.274835",
"voided": false,
"void_reason": null,
"payment_id": null
},
// ... the night of 2026-11-01
{
"id": "442f2691-f69f-4da3-bfc6-de650d9a9866",
"type": "INCIDENTAL",
"description": "Airport transfer",
"amount": 35.0,
"service_date": "2026-10-10",
"posted_at": "2026-10-10T05:09:47.387569",
"voided": false,
"void_reason": null,
"payment_id": null
}
],
"total_charges": 215.0,
"total_payments": 0.0,
"balance": 215.0,
"payments": []
}
}Errors
| Status | detail | When |
|---|---|---|
409 | A cancelled booking takes no new charges. | |
409 | The stay is over: the hotel adds any late charge itself. | The guest has checked out |
403 | The app token lacks folios:write | |
404 | Reservation not found | |
422 | description empty or over 120 characters, amount not above 0, quantity out of range |
Record a payment
/reservations/{reservation_id}/folio/paymentsfolios:writeOperation folio.addPaymentRecords money you took for the hotel (on your own payment gateway, say), so the bill shows it paid. ChatBeds does not move any money here. You can record at most what is owed. Returns the payment and the updated folio.
Body
balance.CASH, CARD or BANK_TRANSFER.Example
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/folio/payments" \
-H "Authorization: Bearer cbk_••••" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: BK-PAY-88231" \
-d '{"amount": 100, "method": "CARD", "reference": "BK-PAY-88231"}'{
"payment": {
"id": "763300e8-3898-4fba-a0b0-0a0cc86ba611",
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"kind": "PAYMENT",
"amount": 100.0,
"currency": "USD",
"method": "CARD",
"status": "COMPLETED",
"reference": "BK-PAY-88231",
"paid_at": "2026-10-10T05:09:47.406608+00:00",
"created_at": "2026-10-10T05:09:47.405620+00:00",
"url": null,
"expires_at": null
},
"folio": {
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"currency": "USD",
"lines": [
// ... the two nights and the airport transfer, as above
{
"id": "d3dc1f18-4b15-42b5-bf9f-a3b375b3435e",
"type": "PAYMENT",
"description": "Paid through Sandbox key",
"amount": 100.0,
"service_date": null,
"posted_at": "2026-10-10T05:09:47.406626",
"voided": false,
"void_reason": null,
"payment_id": "763300e8-3898-4fba-a0b0-0a0cc86ba611"
}
],
"total_charges": 215.0,
"total_payments": 100.0,
"balance": 115.0,
"payments": [
{
"id": "763300e8-3898-4fba-a0b0-0a0cc86ba611",
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"kind": "PAYMENT",
"amount": 100.0,
"currency": "USD",
"method": "CARD",
"status": "COMPLETED",
"reference": "BK-PAY-88231",
"paid_at": "2026-10-10T05:09:47.406608+00:00",
"created_at": "2026-10-10T05:09:47.405620+00:00",
"url": null,
"expires_at": null
}
]
}
}The payment line reads "Paid through" and your key's or app's name, so the hotel knows where the money is.
Errors
| Status | detail | When |
|---|---|---|
400 | Only USD 115.00 is owed on this booking. | amount is more than the balance |
403 | The app token lacks folios:write | |
404 | Reservation not found | |
422 | amount not above 0, or method not one of the three |
Create a payment link
/reservations/{reservation_id}/payment-linkpayments:writeOperation payment.createLinkMakes a Stripe Checkout page on the hotel's own Stripe account for the guest to pay by card. The money goes to the hotel; ChatBeds marks the payment completed when Stripe confirms it. The link stays open for 23 hours. Send the returned url to the guest.
It works only when the hotel has connected Stripe: check features.payment_links in GET /capabilities.
Body
Example
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/payment-link" \
-H "Authorization: Bearer cbk_••••" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: BK-104233-link-1" \
-d '{}'The sandbox hotel has no Stripe account connected, so the recorded call answers 400:
{
"detail": "Card payments are not set up for this hotel. An owner connects Stripe on the Finance page."
}With Stripe connected, the answer is 200 OK with {"payment": {...}}: a payment with method: "STRIPE", status: "PENDING", the Checkout page in url and its expires_at.
To hear when it is paid, turn on the payment.completed webhook. As a fallback, poll payment.getStatus.
Open links also show on the reservation, in payment_links. When a booking changes and its open links together ask more than is now owed, they are voided and listed in the change's voided_payment_links (see Modify a reservation). Cancelling a booking voids its open links too.
Errors
| Status | detail | When |
|---|---|---|
400 | Card payments are not set up for this hotel. An owner connects Stripe on the Finance page. | No Stripe. Do not offer card payment for this hotel |
400 | Nothing is owed on this booking. | No amount and the balance is 0 |
400 | A card payment link for ... is already open for what is owed. | A link for the whole balance is still open. Use it, or wait for it to expire |
400 | Only ... is owed on this booking (... more is on a card link still open). | amount is more than is owed |
402 | The hotel's plan does not include card payments | |
409 | This booking is cancelled. | |
502 | Stripe could not be reached. Try again in a moment., Stripe did not accept the hotel's key. ..., or Stripe: ... with Stripe's message | Stripe refused or did not answer. No link was made; retry later, or tell the hotel if its key was refused |
403 | The app token lacks payments:write | |
404 | Reservation not found |
One payment link for several bookings
/payment-linkspayments:writeOperation payment.createCombinedLinkOne Stripe page for a multi-room cart: the guest pays the total once, and each booking gets its own payment on its own folio. Each room is then paid, and tracked, on its own: payment.getStatus for each payment_id, and a payment.* webhook for each booking. The bookings must be at the same property and in the same currency.
{reservation_id, amount?}. amount: what to take for that booking, at most what it owes less any card link still open on it. Leave it out for what it owes.curl -X POST "https://app.chatbeds.app/partner/v1/payment-links" \
-H "Authorization: Bearer cbk_••••" \
-H "Idempotency-Key: cart-7781-pay" \
-H "Content-Type: application/json" \
-d '{"reservations": [{"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e", "amount": 100.00},
{"reservation_id": "7c1e2b90-5f4a-4d61-9a3b-2e8f0c6d1a77", "amount": 70.00}]}'{
"payment": {
"url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3",
"status": "PENDING",
"currency": "EUR",
"amount": 170.0,
"expires_at": "2026-11-07T09:12:00Z",
"payments": [
{ "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e", "payment_id": "0d6b0c1e-9a51-4c43-8e1f-3b7f6f2d9a10", "amount": 100.0, "status": "PENDING" },
{ "reservation_id": "7c1e2b90-5f4a-4d61-9a3b-2e8f0c6d1a77", "payment_id": "5e2f8a44-1c3b-47d0-b6a9-0f1e2d3c4b5a", "amount": 70.0, "status": "PENDING" }
]
}
}When the guest pays, every payment on the page completes together and each booking's balance goes down by its own amount. Voiding any one of the payments (payment.void), or a change that voids one, closes the page for all of them: make a new link for what is still owed.
Errors
| Status | detail | When |
|---|---|---|
400 | Card payments are not set up for this hotel. ... | No Stripe |
400 | Nothing is owed on booking ... (... is on a card link still open). | No amount and nothing is left to take on that booking |
400 | Only ... is owed on booking ... | An amount is more than that booking owes |
400 | Each booking can be on the link once., All the bookings on one link must be ... | The same booking twice, or bookings at different properties or in different currencies |
404 | Reservation not found | A booking that isn't this key's property's |
409 | Booking ... is cancelled. | |
422 | No bookings, or more than 20 |
Void a payment link
/payments/{payment_id}/voidpayments:writeOperation payment.voidCloses a card payment link nobody has paid, at Stripe too, so the guest can no longer pay it. The payment's status becomes VOIDED and url becomes null. Use it before making a new link for a different amount.
- If Stripe says the link was paid in the meantime, the payment is recorded and returned with
status: "COMPLETED". Nothing is voided. - Voiding a link that is already voided, expired or paid returns it unchanged.
- Send an
Idempotency-Keyas on any write.
It works only when the hotel has connected Stripe: check features.void_payment_link in GET /capabilities.
Parameters
id.Example
curl -X POST "https://app.chatbeds.app/partner/v1/payments/0b6f3d2a-91c4-4e57-8a1d-3f2e5c7b9a14/void" \
-H "Authorization: Bearer cbk_••••" \
-H "Idempotency-Key: BK-104233-void-link-1"{
"payment": {
"id": "0b6f3d2a-91c4-4e57-8a1d-3f2e5c7b9a14",
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"kind": "PAYMENT",
"amount": 180.0,
"currency": "USD",
"method": "STRIPE",
"status": "VOIDED",
"reference": null,
"paid_at": null,
"created_at": "2026-10-19T09:02:11.204518+00:00",
"url": null,
"expires_at": "2026-10-20T08:02:11.204518+00:00"
}
}Errors
| Status | detail | When |
|---|---|---|
400 | Only a card payment link can be voided. | A payment recorded by hand, or a refund |
502 | Stripe could not be reached. Try again in a moment., or Stripe: ... with Stripe's message | Nothing was changed. Retry with the same Idempotency-Key |
403 | The app token lacks payments:write | |
404 | Payment not found | Not a payment at this property |
Get a payment
/payments/{payment_id}folios:readOperation payment.getStatusReturns one payment at the property: one you recorded, a payment link, or a payment taken at the front desk.
Parameters
id, from a payment link, a recorded payment or the folio.Example
curl -X GET "https://app.chatbeds.app/partner/v1/payments/763300e8-3898-4fba-a0b0-0a0cc86ba611" \
-H "Authorization: Bearer cbk_••••"{
"payment": {
"id": "763300e8-3898-4fba-a0b0-0a0cc86ba611",
"reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
"kind": "PAYMENT",
"amount": 100.0,
"currency": "USD",
"method": "CARD",
"status": "COMPLETED",
"reference": "BK-PAY-88231",
"paid_at": "2026-10-10T05:09:47.406608+00:00",
"created_at": "2026-10-10T05:09:47.405620+00:00",
"url": null,
"expires_at": null
}
}The payment object
| Field | Meaning |
|---|---|
kind | PAYMENT or REFUND |
method | CASH, CARD, BANK_TRANSFER, or STRIPE for a payment link |
status | See below |
reference | The reference you or the hotel gave. Always null for STRIPE |
paid_at | When it was paid; set only when COMPLETED |
url | The Checkout page; set only while PENDING |
expires_at | When a payment link closes |
| Status | Meaning |
|---|---|
PENDING | A payment link not paid yet. url is the page to send |
COMPLETED | Paid. Counts on the folio |
EXPIRED | A payment link nobody paid before expires_at. Create a new one |
VOIDED | A payment link closed unpaid by payment.void, a cancellation or a shorter stay; or a payment the hotel took off the folio |
FAILED | The payment did not go through |
Errors
| Status | detail | When |
|---|---|---|
403 | The app token lacks folios:read | |
404 | Payment not found | Not a payment at this property |
Give a charge free
/reservations/{reservation_id}/folio/lines/{line_id}/complimentaryfolios:writeOperation folio.compMakes a charge complimentary: a night, a minibar item, a laundry, a fee. The line stays on the bill at its price, marked complimentary with your reason, and isn't charged; its tax comes off with it. The balance goes down by its amount. The hotel sees who gave it free and why on the booking's history.
To add an extra already free, use reservation.addExtra with complimentary: true. Extras that always come with the room are included on extra.list.
id from folio.get.Room not ready on arrival.curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/folio/lines/7c3e1a90-2b4d-4f6e-8a1c-5d9b3e7f2a14/complimentary" \
-H "Authorization: Bearer cbk_••••" -H "Content-Type: application/json" \
-H "Idempotency-Key: comp-7c3e1a90" \
-d '{"reason": "Room not ready on arrival"}'{
"id": "7c3e1a90-2b4d-4f6e-8a1c-5d9b3e7f2a14",
"type": "INCIDENTAL",
"description": "Laundry",
"amount": 15.0,
"voided": true,
"void_reason": "Complimentary: Room not ready on arrival",
"complimentary": true
}The answer is {"folio": {...}}, the whole bill as folio.get gives it.
Errors
| Status | When |
|---|---|
400 | The reason is shorter than 3 characters, or the line is a payment, a refund or a tax line (void a payment link with payment.void; tax follows its charge) |
404 | Not a line of this booking's bill |
409 | The line is already off the bill, or the stay is over or cancelled (the hotel changes a closed bill itself) |
403 | The app token lacks folios:write |
Refunds
ChatBeds does not refund through Stripe by itself, not on a cancellation and not on a cheaper change.
- The reservation shows what the hotel owes back in
refund_due(and a negativebalance). - The hotel refunds the guest in its own Stripe dashboard, or in cash or by bank transfer.
- The hotel records the refund on the bill in ChatBeds. It appears as a payment with
kind: "REFUND", andrefund_duegoes down. - If you turned it on, you get a
payment.refundedwebhook with the refund and its amount.
The partner API cannot make refunds. Tell the guest the hotel will refund them, and use refund_due to show how much.
Что-то создаёте?
Guests
Search, read, add and change guest profiles: contact details, nationality, language, company, preferences and notes.
Test tools (staging)
Reset the test hotel, move its clock, send yourself webhook events and replay them, read the API log, and simulate card payments and guests' WhatsApp messages. Staging only.