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://api.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://api.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. Check with 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 |
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 |
Refunds
Refunds are made by the hotel, not through the API. After a cancellation, a negative balance is what the hotel owes the guest.
Testing
The Sandbox Hotel has no Stripe account, so payment.createLink answers 400 there: use it to test that you handle a hotel without card payments. Recording payments works normally in the sandbox.
Building something?