Troubleshooting: payment isn't recording

When payment fails, the invoice or order stays unpaid and the guest is standing at the desk. This article walks through the common diagnoses fast so you can resolve in front of the guest.

Check 1 — Payment method exists and is active

Settings → Payment Methods → confirm the method (Cash, Visa, Bank Transfer, Room Charge) exists and isActive is on. For POS payments specifically, the method also needs to be allowed at this POS point — check the POS point's payment-method config. If the method appears in the dropdown but errors on selection, it's the POS-point allowlist.

Check 2 — Amount matches

The amount field defaults to the invoice/order outstanding total. Override only when taking a partial payment — and confirm the method supports partials. Over-payments (more than the outstanding total) error by default; HotelBee doesn't auto-create credit balances. To handle a tip or rounding excess, take the exact amount and record the difference separately as a tip line.

Check 3 — Stripe response (for card payments)

If the method is a Stripe-backed card, the error message comes from Stripe directly. Common decline reasons:

• card_declined / do_not_honor — bank declined; have guest call bank or try another card.
• insufficient_funds — guest's account doesn't have the amount.
• expired_card — visible from the card itself; ask for a current one.
• incorrect_cvc / processing_error — re-enter the card or try again — sometimes transient.
• fraudulent / stolen_card / lost_card — don't retry; contact the guest's bank.

Check 4 — Shift is open (cash payments)

Cash payments record into the active shift. If you haven't started one, the cash payment errors. Dashboards → My Shift → Start Shift, enter opening cash, and try again.

Check 5 — Payment account behind the method

Each payment method points to a payment account (the chart-of-accounts row that receives the funds). If that account is missing or inactive, the payment errors with 'payment account not found' or similar. Settings → Payment Accounts → confirm the linked account exists and is active. Also relevant for fiscal: bank-transfer methods need a linked bank account with full IBAN, name, bank fields populated, or fiscal submission fails (separate troubleshooting article).

Resolution patterns

• Card declined → ask for another card or call to bank. Don't retry the same card more than once.
• Method missing → settings fix; takes a minute, no need to keep guest waiting at the desk while you sort it.
• Shift not open → start it now, retry the payment.
• Persistent error after these → check audit log on the invoice for the exact failure, contact support with the invoice ID and error message.