Refund processor error β full-screen dialog for multi-line messages
When a refund attempted through a payment processor fails, the current experience displays the error in a format matched to the message length. Short error messages appear as brief toast notifications. Longer processor responses β those that exceed a single line β appear in a full-screen payment error dialog, so the complete message is always readable without truncation.
Audience: Front desk staff processing refunds in the current point of sale (POS) experience.
On this page
Before you begin
- Your organization must be using the current POS experience to see this behavior. The legacy experience handles processor error display differently.
- You must have the Service Refund permission (under Security Roles > [your role] > Permissions tab > Appointment Book > ServiceRefund) to process service refunds.
- For product refunds, the Allow product refund by cash organization-level setting must be enabled at Configuration > POS > Essentials.
- The refund must be initiated through the Appointment Book: navigate to the invoice, select I want to from the three-dot menu, then choose Refund Invoice.
How error display works
When you attempt a refund and the payment processor responds with an error, the current experience determines how to present the error based on the length of the processor's response:
- Short error messages β displayed as a toast notification at the bottom of the screen. Toasts are brief and self-dismissing, suited to concise one-line responses such as "Card expired."
- Multi-line error messages β displayed in a full-screen payment error dialog. When the processor returns a response that exceeds a single line, the system shows the complete message in a dedicated dialog so nothing is cut off. Staff can read the full error text and decide how to respond.
This distinction means staff always see the complete error regardless of how much detail the processor includes in its response. You do not need to take any action to switch between these display modes β the system selects the appropriate format automatically based on the processor response.
Steps
Attempt a refund
- From the Appointment Book, locate the closed invoice you want to refund.
- Select the three-dot menu on the invoice, then select I want to > Refund Invoice.
- On the refund selection screen, choose the refund mode and confirm the items and amounts to refund.
- Submit the refund request.
Read the error when a refund fails
If the payment processor declines or fails to process the refund, the current experience displays the error in one of two ways:
For short, single-line processor errors: The error appears as a toast notification. The toast is brief and dismisses automatically. Note the message, then decide whether to retry or contact your manager.
For longer, multi-line processor errors: The error appears in a full-screen payment error dialog. The dialog displays the complete processor response without truncation. Read the full message before proceeding. Select the option to dismiss the dialog when you are done.
Respond to the error
- Review the error message in full. Multi-line responses from the processor often include reason codes, partial details, or instructions relevant to the specific failure.
- Take the appropriate action based on the error:
- If the error indicates a network or timeout issue, wait a moment and retry the refund.
- If the error indicates a card or account issue, ask the guest to provide an alternative refund method.
- If the error is unclear or the retry continues to fail, contact your center manager or Zenoti Support.
Important: Do not close the invoice or navigate away from the refund screen until you have recorded or resolved the error. Navigating away without completing the refund does not automatically cancel the refund attempt on the processor side.
Tips
- Record the full error text. When the full-screen dialog appears, take a note of the complete message before dismissing it. This helps when escalating to your manager or Zenoti Support.
- Retry once before escalating. Transient network conditions can cause refund failures. A single retry is often sufficient for timeout-related errors.
- Try a different refund method if the processor error persists. Refund amounts can be split across multiple payment types β for example, part refunded to the original card and part issued as store credit β so a failed card refund does not always mean the guest cannot be refunded at all.
Troubleshooting
The error dialog appeared but dismissed too quickly and I could not read it.
The full-screen payment error dialog stays on screen until you actively dismiss it. If the message disappeared immediately, it was most likely a short error displayed as a toast. Retry the refund and observe whether the error reappears as a toast or as a dialog. If you need the exact processor message, contact Zenoti Support and reference the invoice number and approximate time of the attempt.
I see a toast error but the message is cut off.
Toasts are used for short, single-line error responses from the processor. If the message appears truncated in a toast, it is because the processor returned a shorter response. The full-screen dialog is reserved for responses the system identifies as exceeding a single line. If you believe a relevant detail is missing, retry the refund; if the underlying error produces a multi-line response on retry, the dialog will appear.
The refund screen shows an error but the guest's card statement shows a pending charge.
A failed refund in Zenoti does not necessarily mean a charge was successfully posted. However, processor states can differ from Zenoti's record. Ask the guest to allow one to two business days for the charge to resolve, and contact your payment processor or Zenoti Support with the transaction details if the discrepancy persists.