ZenotiHelp

Account Holder KYC Orchestration

ZTZenoti Docs Team Updated August 16, 2026 7 min readGuide

This article explains how Zenoti coordinates the identity verification sequence for a wallet account holder during tips payout onboarding. The orchestration process runs three steps in order β€” Terms and Conditions acceptance, Enhanced Due Diligence (EDD) submission, and KYC initiation β€” and uses an internal processing queue to track and gate each step.

Audience: Zenoti administrators and center managers who oversee tips payout onboarding and need to understand what happens during identity verification, how failures are handled, and when re-submission is available.


On this page


Before you begin

  • Tips payout onboarding must be active for the center. See Set up Same-Day Tip Payouts for your business.
  • The account holder must not already have an approved KYC status. If KYC is already approved, the system returns error AH026 ("Account Holder KYC already approved") and no further action is needed.
  • The account holder must not already be linked to another account. If so, the system returns error AH024 ("Account Holder is already linked").

Permission: You need the Configure Payment Settings permission to manage tips payout onboarding and KYC configuration. Admin path: Configuration > Security > Security roles, then open the relevant role and enable Configure Payment Settings under the Payments group.


How the KYC orchestration sequence works

When a wallet account holder completes the onboarding form, Zenoti runs a three-step verification sequence automatically. The steps run in strict order:

  1. Terms and Conditions acceptance β€” All required disclosures are submitted to the banking provider and acknowledged.
  2. Enhanced Due Diligence (EDD) submission β€” Additional identity information is submitted to the banking provider.
  3. KYC initiation β€” Identity verification is formally initiated with the banking provider.

Each step is tracked in a processing queue. A step must complete successfully before the next step begins. If a step fails, the queue entry for that step is aborted and an error is logged. The behavior differs by step: a Terms and Conditions failure stops the entire sequence for that run, while an EDD failure is logged but does not prevent KYC initiation from proceeding.

Note: This sequence runs automatically as part of onboarding. You do not manually trigger each step. If a step fails, see Troubleshooting below for resolution options.


Step 1 β€” Terms and Conditions acceptance

What the system does

When the processing queue contains a pending Terms and Conditions acceptance entry for the account holder, the system:

  1. Begins processing the queue entry.
  2. Submits all pending disclosures to the banking provider, recording each as acknowledged.
  3. Records the acceptance timestamp for each disclosure.
  4. Marks the queue entry as finished.
  5. Proceeds to Step 2 (EDD submission).

The disclosures submitted during this step include the following agreements, which the account holder reviews during onboarding:

Disclosure Display label
Consumer ACH Authorization and Agreement Consumer ACH Authorization and Agreement
Electronic Communication Agreement Electronic Communication Agreement
Privacy Notice Privacy Notice
Smartcard Agreement Smartcard Agreement

What happens if Terms and Conditions acceptance fails

If submission fails for any individual disclosure, the system:

  • Logs the error, including the disclosure type and the account holder identifier.
  • Aborts the processing queue entry.
  • Does not proceed to KYC initiation in the same run.

Important: A Terms and Conditions failure stops the entire orchestration sequence for that run. The account holder cannot proceed to KYC until the Terms and Conditions step completes successfully. See Re-submitting disclosures and EDD independently for how to retry.


Step 2 β€” Enhanced Due Diligence submission

What the system does

After Terms and Conditions acceptance completes, the system checks whether a pending EDD entry exists in the processing queue. If one is present, the system:

  1. Submits the EDD information to the banking provider.
  2. On a successful response, stores the external EDD identifier in the processing queue record and marks the entry as finished.
  3. On a failure, aborts the queue entry and logs the error.

What happens if EDD submission fails

Unlike a Terms and Conditions failure, an EDD submission failure does not stop the sequence. The system logs the failure and continues to Step 3 (KYC initiation).

Note: If EDD submission fails, the failure is recorded for review. KYC initiation still proceeds. Contact Zenoti support if EDD failures recur, as they may indicate a data issue with the account holder's submitted information.


Step 3 β€” KYC initiation

What the system does

After the Terms and Conditions step completes (and regardless of EDD outcome), the system initiates identity verification:

  1. Creates a KYC history record for the account holder with a status of Pending and a message of "Initiated".
  2. Submits the verification initiation request to the banking provider.

KYC initiation outcomes

Outcome What happens next
Initiation succeeds The account holder's KYC status moves to Pending while the banking provider reviews the submission.
Initiation fails Error AH004 ("Exception occurred while calling initiate verification") is logged. The KYC history record remains with Pending status. Contact Zenoti support to retry.

Note: KYC review is performed by the banking provider and may take time to complete. The account holder's wallet is not active until KYC is approved.

Worked example

Example: A new account holder named Jordan Lee completes the onboarding form for the downtown center. The system processes the queue:

  • Step 1: All four disclosures (Consumer ACH Authorization and Agreement, Electronic Communication Agreement, Privacy Notice, Smartcard Agreement) are submitted and acknowledged. The queue entry is marked finished.
  • Step 2: EDD information is submitted. The banking provider returns a success response and the external EDD identifier is stored. The queue entry is marked finished.
  • Step 3: A KYC history record is created with status Pending and message "Initiated". The verification request is submitted to the banking provider.

Jordan's wallet remains inactive while the banking provider reviews the submission. Once KYC is approved, the wallet becomes active and tips payout can begin.


Re-submitting disclosures and EDD independently

If a previous orchestration run failed at the Terms and Conditions or EDD step, you can re-submit disclosures and EDD without running the full onboarding sequence again. This is available as a separate action for retry scenarios.

Use this option when:

  • The initial Terms and Conditions submission failed and the account holder has not yet proceeded to KYC.
  • EDD submission failed and you want to re-submit EDD data before the next scheduled orchestration run.

Important: Re-submitting disclosures and EDD does not automatically trigger KYC initiation. KYC initiation runs as part of the full orchestration sequence. If you need KYC to initiate after re-submission, contact Zenoti support to trigger the full sequence.

To re-submit disclosures and EDD:

  1. Navigate to Configuration > Payments > Tips Payout.
  2. Locate the account holder whose verification is incomplete.
  3. Select the re-submission action for that account holder.
  4. Confirm the action. The system re-submits all pending disclosures and EDD information to the banking provider.

Note: If the account holder's KYC is already approved, re-submission is not available. The system returns error AH026 ("Account Holder KYC already approved").


Tips

  • Check the processing queue status before contacting support. If onboarding appears stalled, the most common cause is a failed Terms and Conditions submission. Use the re-submission action to retry before escalating.
  • EDD failures do not block KYC. If you see an EDD error in the logs but the account holder's KYC status shows Pending, the sequence completed normally. EDD data can be re-submitted separately if needed.
  • KYC approval timing varies. The banking provider controls how long KYC review takes. Do not assume a delay indicates a failure β€” check the account holder's KYC history record for the current status before taking action.
  • Each center is onboarded independently. KYC orchestration runs per account holder per center. An account holder who is verified for one center is not automatically verified for another.

Troubleshooting

The account holder's KYC status has not changed after onboarding.

The processing queue may have stalled at the Terms and Conditions step. Check whether a Terms and Conditions failure was logged for this account holder. If so, use the re-submission action described in Re-submitting disclosures and EDD independently. If the queue entry shows no error but KYC has not progressed, contact Zenoti support.

Error AH004 appears after KYC initiation.

This error ("Exception occurred while calling initiate verification") indicates the banking provider rejected or could not process the initiation request. The KYC history record is created with Pending status, but the provider did not confirm receipt. Contact Zenoti support to retry the initiation request.

Error AH026 appears when attempting re-submission.

This error ("Account Holder KYC already approved") means the account holder's identity verification is complete. No further action is needed. If the account holder's wallet is still inactive despite approved KYC, contact Zenoti support to investigate the wallet activation status.

Error AH002 appears during onboarding.

This error ("Account Holder already exists") means an account holder record already exists for this individual. The system will not create a duplicate. Locate the existing account holder record and verify its KYC status before proceeding.

EDD submission fails repeatedly.

Repeated EDD failures may indicate that the account holder's submitted information does not match what the banking provider expects. Review the account holder's personal information for accuracy (name, date of birth, address). Contact Zenoti support if the issue persists after verifying the data.


Was this article helpful?
Your feedback helps us improve our documentation.