এই পাতাটি এখনও অনুবাদ হয়নি, তাই আপনি ইংরেজি সংস্করণ পড়ছেন।
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... | Use | Scope |
|---|---|---|
| Took the money yourself (your own gateway, a prepaid OTA booking) | Record a payment | folios:write |
| Want the guest to pay the hotel by card | Send a payment link | payments:write |
| Want to show what's owed | Read the folio | folios: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.
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" }'{
"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 }
}amountcan be at most the folio'sbalance.methodisCASH,CARDorBANK_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.
Send a payment link
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.
Create the link
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.
| Status | Meaning |
|---|---|
PENDING | Not paid yet |
COMPLETED | Paid; on the folio |
EXPIRED | Not paid in 23 hours. Make a new link if still needed |
VOIDED | Closed unpaid: by you, a cancellation or a shorter stay |
FAILED | The payment didn't go through |
Errors to expect
| Status | detail | Do |
|---|---|---|
400 | Card payments are not set up for this hotel. An owner connects Stripe on the Finance page. | Hide card payment for this hotel |
400 | A card payment link for ... is already open for what is owed. | Reuse the open link, or wait for it to expire |
402 | The hotel's plan doesn't include card payments | |
502 | Stripe 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.
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.
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 }'Fix the payment link
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:
GET /reservations/{id}/cancellation-quote. It gives thefee, theexplanation, and what the guest would owe (balance_after) or be owed back (refund_due_after).- Show the guest the fee and the explanation.
POST /reservations/{id}/cancel. The fee is the one quoted, unlessfree_untilpassed 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.
কিছু বানাচ্ছেন?