ChatBedsGeliştiriciler
Rehberler

Bu sayfa henüz çevrilmedi, bu yüzden İngilizce sürümünü okuyorsunuz.

Take payments

Two ways to handle money on a ChatBeds booking. Record a payment you took yourself, or send the guest a card payment link on the hotel's own Stripe.

Bookings made through the API are pay at the hotel: the folio shows the full amount owed. If money changes hands before the stay, tell ChatBeds, so the hotel doesn't charge the guest twice.

You...UseScope
Took the money yourself (your own gateway, a prepaid OTA booking)Record a paymentfolios:write
Want the guest to pay the hotel by cardSend a payment linkpayments:write
Want to show what's owedRead the foliofolios:read

Record a payment you took

ChatBeds moves no money here: you record what you already collected, so the bill shows it paid and the hotel can match it.

Request
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/$RESERVATION/folio/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-BK-PAY-88231" \
  -d '{ "amount": 100.0, "method": "CARD", "reference": "BK-PAY-88231" }'
Response (trimmed)
{
  "payment": {
    "id": "763300e8-3898-4fba-a0b0-0a0cc86ba611",
    "kind": "PAYMENT",
    "amount": 100.0,
    "currency": "USD",
    "method": "CARD",
    "status": "COMPLETED",
    "reference": "BK-PAY-88231"
  },
  "folio": { "total_charges": 180.0, "total_payments": 100.0, "balance": 80.0 }
}
  • amount can be at most the folio's balance.
  • method is CASH, CARD or BANK_TRANSFER.
  • Put your transaction ID in reference: it's what the hotel's accountant will look for.
  • Always send an Idempotency-Key. A retried payment without one is recorded twice.

How you settle with the hotel (passing the money on, your commission) is between you and the hotel; ChatBeds only records it.

ChatBeds makes a Stripe Checkout page on the hotel's own Stripe account. The guest pays the hotel directly; you never touch card details.

Check the hotel can take cards

GET /capabilities has features.payment_links. If it's false, the hotel hasn't connected Stripe (or its plan doesn't include card payments): don't offer card payment for this hotel.

Request
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/$RESERVATION/payment-link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: link-BK-104233" \
  -d '{ "amount": 80.0 }'

Leave out amount to ask for everything owed. The answer is a payment with status: "PENDING", a url and expires_at (23 hours from now).

Send it to the guest

By email, SMS or in your app. The page shows the hotel's name and the amount.

Check it was paid

ChatBeds marks the payment COMPLETED when Stripe confirms it. Turn on the payment.completed webhook and ChatBeds tells you at once, with the payment and the booking. payment.failed and payment.expired tell you when a link didn't work out.

Keep polling as a fallback, in case a webhook is late: check GET /payments/{id}, or read the folio's balance.

StatusMeaning
PENDINGNot paid yet
COMPLETEDPaid; on the folio
EXPIREDNot paid in 23 hours. Make a new link if still needed
VOIDEDClosed unpaid: by you, a cancellation or a shorter stay
FAILEDThe payment didn't go through

Errors to expect

StatusdetailDo
400Card payments are not set up for this hotel. An owner connects Stripe on the Finance page.Hide card payment for this hotel
400A card payment link for ... is already open for what is owed.Reuse the open link, or wait for it to expire
402The hotel's plan doesn't include card payments
502Stripe could not be reached. Try again in a moment.No link was made; retry later

Changing and cancelling a booking

When the price of a booking changes, so does what the guest owes. Keep links and the bill in step.

Preview the change

Send the change to PATCH /reservations/{id}?dry_run=true. Nothing is saved. The answer has before, after and difference.

Request
curl -X PATCH "https://app.chatbeds.app/partner/v1/reservations/$RESERVATION?dry_run=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "departure": "2026-11-01" }'

Show the guest

Show after.total and difference. A negative difference is a cheaper stay.

Save it at that price

Send the same body to PATCH /reservations/{id} with after.total as expected_total and an Idempotency-Key. If the price moved since the preview, you get 409 and nothing is saved: preview again.

Request
curl -X PATCH "https://app.chatbeds.app/partner/v1/reservations/$RESERVATION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: change-BK-104233-1" \
  -d '{ "departure": "2026-11-01", "expected_total": 90.0 }'

If the open links now ask more than is owed, ChatBeds voids them all, at Stripe too, and lists them in voided_payment_links. Make one new link for what is owed. To change a link yourself, void it with POST /payments/{id}/void, then create a new one.

To cancel:

  1. GET /reservations/{id}/cancellation-quote. It gives the fee, the explanation, and what the guest would owe (balance_after) or be owed back (refund_due_after).
  2. Show the guest the fee and the explanation.
  3. POST /reservations/{id}/cancel. The fee is the one quoted, unless free_until passed in between. Open payment links are voided.

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. The hotel refunds the guest in its Stripe dashboard (or in cash or by bank transfer) and records it on the bill. If you turned it on, you get a payment.refunded webhook with the amount (a payment with kind: "REFUND"). See Refunds.

Testing

The Sandbox Hotel has no Stripe account, so payment.createLink answers 400 there and features.void_payment_link is false: use it to test that you handle a hotel without card payments. Recording payments works normally in the sandbox.

Bir şey mi geliştiriyorsunuz?

Bu sayfada