Payout fund transfer β enhanced failure tracking
When a fund transfer attempt fails, Zenoti records the failure details β including the transfer amount, the available balance at the time of the attempt, a failure code, and the stage at which the failure occurred β so that administrators and support teams can diagnose and resolve payout issues quickly.
Audience: Organization administrators and support staff who investigate payout failures and reconcile fund transfer activity.
Before you begin
- You must have access to fund transfer attempt records in Zenoti. Contact your administrator if you cannot view payout or fund transfer data.
- Confirm that the payout in question has been processed (or attempted) before reviewing failure details β records are created at the time of each attempt.
Permission: You need the appropriate administrative permission to view fund transfer attempt records. Contact your Zenoti administrator to confirm your role includes access to payout management data.
Steps
View failure details for a fund transfer attempt
When a fund transfer attempt fails, Zenoti automatically records the following details on the attempt record:
- Transfer amount β The amount that was submitted for transfer at the time of the attempt.
- Available balance β The balance available in the funding account at the time the transfer was attempted.
- Failure code β A code identifying the specific error returned at the point of failure.
- Failure stage β The stage in the transfer process at which the failure occurred.
- Associated fund transfer references β The primary keys linking this attempt to the related fund transfer records.
Note: The failure code and failure stage fields are populated only when an attempt fails. For successful transfers, these fields remain empty.
To investigate a failed fund transfer:
Navigate to the payout or fund transfer section of the payment dashboard.
Locate the fund transfer record you want to investigate.
Open the attempt history for that fund transfer to view individual attempt records.
Review the following fields on the failed attempt record:
- Failure code β Use this code to identify the category of error. Common failure codes indicate issues such as insufficient balance, processor rejection, or network errors. Share this code with Zenoti support when escalating an issue.
- Failure stage β Use this field to identify where in the transfer process the failure occurred. For example, a failure at an early stage may indicate a balance or eligibility issue, while a failure at a later stage may indicate a processor or network issue.
- Available balance β Compare this value to the transfer amount. If the available balance was lower than the transfer amount at the time of the attempt, the failure may be due to insufficient funds.
- Transfer amount β Confirm this matches the expected payout amount for the period.
Use the associated fund transfer references to cross-reference the failed attempt with the parent fund transfer record and any related transactions.
Diagnose the failure using failure code and stage
Once you have the failure code and failure stage from the attempt record, use the following approach to determine the cause and next steps:
- Note the failure stage to understand where in the process the transfer stopped.
- Note the failure code to identify the specific error type.
- Compare the available balance at the time of the attempt against the transfer amount:
- If the available balance was less than the transfer amount, the transfer may have failed due to insufficient funds. Verify that the funding account has adequate balance before retrying.
- If the available balance was sufficient, the failure code and stage provide the primary diagnostic signal. Escalate to Zenoti support with both values.
- If the failure is recurring across multiple attempts, check whether the failure code and stage are consistent. Consistent failures at the same stage with the same code indicate a systemic issue rather than a transient one.
Tip: When contacting Zenoti support about a payout failure, always provide the failure code, failure stage, available balance, and transfer amount from the attempt record. This information allows support to diagnose the issue without additional investigation steps.
Escalate a persistent payout failure
If a fund transfer continues to fail after reviewing the available balance and failure details:
- Gather the following from the failed attempt record:
- Failure code
- Failure stage
- Available balance at time of attempt
- Transfer amount
- Associated fund transfer references
- Contact Zenoti support and provide all of the above details.
- Support will use the failure code and stage to identify whether the issue is related to the processor, the funding account configuration, or the transfer pipeline.
Important: Do not attempt to manually re-trigger a fund transfer without first understanding the failure cause. Repeated failed attempts may affect your payout schedule or funding account status.
Tips
- Check available balance before each payout cycle. If your available balance is consistently lower than expected transfer amounts, review your reconciliation records to identify timing gaps between collections and available balance updates.
- Use the failure stage as a triage signal. Failures at early stages (before the transfer reaches the processor) are typically configuration or balance issues. Failures at later stages are more likely processor or network issues.
- Keep a record of recurring failure codes. If the same failure code appears across multiple attempts or multiple payout periods, document the pattern and share it with Zenoti support. Recurring codes may indicate a processor-side issue that requires escalation beyond standard troubleshooting.
- Cross-reference with reconciliation. After a failed fund transfer is resolved and retried successfully, verify the outcome in your reconciliation records to confirm the payout was received and matched correctly.
Troubleshooting
The failure code and failure stage fields are blank on an attempt record.
Failure code and failure stage are only populated when an attempt fails. If these fields are blank, the attempt either succeeded or the record has not yet been updated. Refresh the page and confirm the attempt status before investigating further.
The available balance shown on the attempt record is lower than expected.
The available balance is captured at the moment the transfer is attempted. If your balance was recently updated by a collection or reconciliation event, the timing may not align with the attempt. Review your payout schedule and collection timing to identify whether a balance update occurred after the attempt was initiated.
The same failure code appears on every attempt for a fund transfer.
A consistent failure code across multiple attempts indicates a persistent issue rather than a transient one. Do not continue retrying without first resolving the underlying cause. Contact Zenoti support with the failure code, failure stage, and associated fund transfer references to investigate the root cause.
The associated fund transfer references do not match any records in the payment dashboard.
This may indicate a data synchronization delay. Wait a few minutes and refresh the payment dashboard. If the mismatch persists, contact Zenoti support with the attempt record details and the expected fund transfer references.