ChatBedsڈویلپرز
API حوالہ

اس صفحے کا ترجمہ ابھی نہیں ہوا، اس لیے آپ انگریزی ورژن پڑھ رہے ہیں۔

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

GET/reservations/{reservation_id}/folio
Scope folios:readOperation folio.get

Returns every line on the bill (voided lines included and marked), the totals, the balance and the payments.

Parameters

reservation_id uuid (path)required
The reservation.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/folio" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "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
      }
    ]
  }
}
FieldMeaning
lines[].typeROOM_CHARGE (one per night), INCIDENTAL (extras and charges), FEE, TAX, PAYMENT, REFUND
lines[].service_dateThe night or day the charge is for; null for payments
lines[].voidedtrue when the hotel took the line off the bill; void_reason says why. Voided lines do not count in the totals
lines[].complimentarytrue 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_idOn PAYMENT and REFUND lines, the payment it records
total_chargesAll charges not voided
total_paymentsPayments received, less refunds
balancetotal_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[].windowsA charge's amount in each window, like {"1": 20.0, "2": 180.0}
payments[].windowThe window a payment pays

Errors

StatusdetailWhen
403The app token lacks folios:read
404Reservation not found

Add a charge

POST/reservations/{reservation_id}/folio/charges
Scope folios:writeOperation folio.addCharge

Puts 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

reservation_id uuid (path)required
The reservation.
description stringrequired
1 to 120 characters, as the guest will see it, for example Airport transfer.
amount numberrequired
The price of one. More than 0, up to 99,999,999.99, in the booking's currency.
quantity integer
1 to 99. Default 1. Above 1 the line reads Airport transfer x2.

Example

Request
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}'
200 OK
{
  "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

StatusdetailWhen
409A cancelled booking takes no new charges.
409The stay is over: the hotel adds any late charge itself.The guest has checked out
403The app token lacks folios:write
404Reservation not found
422description empty or over 120 characters, amount not above 0, quantity out of range

Record a payment

POST/reservations/{reservation_id}/folio/payments
Scope folios:writeOperation folio.addPayment

Records 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

reservation_id uuid (path)required
The reservation.
amount numberrequired
More than 0, and at most the folio's balance.
method stringrequired
CASH, CARD or BANK_TRANSFER.
reference string
Up to 255 characters: your transaction ID, so the hotel can match it.

Example

Request
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"}'
200 OK
{
  "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

StatusdetailWhen
400Only USD 115.00 is owed on this booking.amount is more than the balance
403The app token lacks folios:write
404Reservation not found
422amount not above 0, or method not one of the three
POST/reservations/{reservation_id}/payment-link
Scope payments:writeOperation payment.createLink

Makes 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

reservation_id uuid (path)required
The reservation.
amount number
More than 0, up to what is owed. Default: everything owed, less any link still open. The body is optional.

Example

Request
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:

400 Bad Request
{
  "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

StatusdetailWhen
400Card 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
400Nothing is owed on this booking.No amount and the balance is 0
400A 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
400Only ... is owed on this booking (... more is on a card link still open).amount is more than is owed
402The hotel's plan does not include card payments
409This booking is cancelled.
502Stripe could not be reached. Try again in a moment., Stripe did not accept the hotel's key. ..., or Stripe: ... with Stripe's messageStripe refused or did not answer. No link was made; retry later, or tell the hotel if its key was refused
403The app token lacks payments:write
404Reservation not found
POST/payment-links
Scope payments:writeOperation payment.createCombinedLink

One 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.

reservations arrayrequired
1 to 20 items, each a booking once: {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.
Request
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}]}'
201 Created
{
  "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

StatusdetailWhen
400Card payments are not set up for this hotel. ...No Stripe
400Nothing is owed on booking ... (... is on a card link still open).No amount and nothing is left to take on that booking
400Only ... is owed on booking ...An amount is more than that booking owes
400Each 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
404Reservation not foundA booking that isn't this key's property's
409Booking ... is cancelled.
422No bookings, or more than 20
POST/payments/{payment_id}/void
Scope payments:writeOperation payment.void

Closes 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-Key as on any write.

It works only when the hotel has connected Stripe: check features.void_payment_link in GET /capabilities.

Parameters

payment_id uuid (path)required
The payment link's id.

Example

Request
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"
200 OK
{
  "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

StatusdetailWhen
400Only a card payment link can be voided.A payment recorded by hand, or a refund
502Stripe could not be reached. Try again in a moment., or Stripe: ... with Stripe's messageNothing was changed. Retry with the same Idempotency-Key
403The app token lacks payments:write
404Payment not foundNot a payment at this property

Get a payment

GET/payments/{payment_id}
Scope folios:readOperation payment.getStatus

Returns one payment at the property: one you recorded, a payment link, or a payment taken at the front desk.

Parameters

payment_id uuid (path)required
The payment's id, from a payment link, a recorded payment or the folio.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/payments/763300e8-3898-4fba-a0b0-0a0cc86ba611" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "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

FieldMeaning
kindPAYMENT or REFUND
methodCASH, CARD, BANK_TRANSFER, or STRIPE for a payment link
statusSee below
referenceThe reference you or the hotel gave. Always null for STRIPE
paid_atWhen it was paid; set only when COMPLETED
urlThe Checkout page; set only while PENDING
expires_atWhen a payment link closes
StatusMeaning
PENDINGA payment link not paid yet. url is the page to send
COMPLETEDPaid. Counts on the folio
EXPIREDA payment link nobody paid before expires_at. Create a new one
VOIDEDA payment link closed unpaid by payment.void, a cancellation or a shorter stay; or a payment the hotel took off the folio
FAILEDThe payment did not go through

Errors

StatusdetailWhen
403The app token lacks folios:read
404Payment not foundNot a payment at this property

Give a charge free

POST/reservations/{reservation_id}/folio/lines/{line_id}/complimentary
Scope folios:writeOperation folio.comp

Makes 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.

reservation_id uuid (path)required
The booking.
line_id uuid (path)required
The charge's id from folio.get.
reason stringrequired
Why it is free, 3 to 200 characters, such as Room not ready on arrival.
Request
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"}'
200 OK (the line, in the folio returned)
{
  "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

StatusWhen
400The 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)
404Not a line of this booking's bill
409The line is already off the bill, or the stay is over or cancelled (the hotel changes a closed bill itself)
403The app token lacks folios:write

Refunds

ChatBeds does not refund through Stripe by itself, not on a cancellation and not on a cheaper change.

  1. The reservation shows what the hotel owes back in refund_due (and a negative balance).
  2. The hotel refunds the guest in its own Stripe dashboard, or in cash or by bank transfer.
  3. The hotel records the refund on the bill in ChatBeds. It appears as a payment with kind: "REFUND", and refund_due goes down.
  4. If you turned it on, you get a payment.refunded webhook 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.

کچھ بنا رہے ہیں؟

اس صفحے پر