Account holder KYC orchestration
When a guest or organization completes onboarding in Zenoti Payments, the system must verify their identity before enabling full payment capabilities. This article explains how Zenoti sequences Know Your Customer (KYC) verification for an account holder — specifically, how Terms and Conditions (T&C) acceptance and Enhanced Due Diligence (EDD) disclosures are processed before KYC verification is submitted to the Banking as a Service (BaaS) provider.
Audience: Payment administrators and operations staff who manage account holder onboarding and monitor KYC verification status.
Before you begin
- The account holder must exist in Zenoti Payments and have a pending KYC verification request.
- You need access to the payment dashboard to monitor KYC status.
- Ensure any required T&C disclosures have been presented to the account holder before initiating this workflow.
Permission: You need the appropriate payment administration permissions to initiate or monitor KYC verification for account holders.
Steps
Understand the KYC orchestration sequence
Before initiating KYC verification, Zenoti processes pending T&C acceptance and EDD disclosures in a specific order. Understanding this sequence helps you diagnose issues when verification does not proceed as expected.
The orchestration follows this order:
- Process pending T&C acceptance — Any pending T&C acceptance actions in the processing queue are completed first. The system submits all pending disclosures to the BaaS provider with an
Acknowledgedevent type and records the acceptance timestamp against the account holder's T&C record. KYC verification does not begin until this step succeeds. - Submit Enhanced Due Diligence (EDD) — As part of the disclosure flow, the system submits EDD for the account holder. On successful submission, the external EDD identifier returned by the BaaS provider is recorded against the processing queue entry.
- Record a KYC history entry — Before calling the BaaS provider's verification endpoint, the system records a KYC history entry with status
Pendingand messageInitiated. This creates an audit trail for each KYC initiation attempt. - Submit KYC verification — The system calls the BaaS provider's verification endpoint to initiate identity verification.
Important: If T&C acceptance or disclosure submission fails at any point, the system aborts the corresponding processing queue entry and does not proceed to KYC verification. You must resolve the failure before KYC can be initiated for that account holder.
Monitor KYC status
After KYC orchestration is initiated, you can monitor the status from the payment dashboard.
- Navigate to the payment dashboard.
- Locate the account holder whose KYC verification you want to monitor.
- Review the KYC history entries to confirm:
- A
Pending/Initiatedentry exists, confirming the verification was submitted to the BaaS provider. - T&C acceptance timestamps are recorded on the account holder's T&C record.
- The EDD external identifier is recorded against the processing queue entry (if EDD was required).
- A
Note: The KYC history entry with status
Pendingand messageInitiatedis created before the BaaS provider call. If you see this entry but no subsequent status update, the BaaS provider may not have responded yet. Allow time for the provider to process the request before escalating.
Resolve a failed T&C or disclosure submission
If the processing queue entry is aborted due to a T&C acceptance or disclosure failure, KYC verification will not proceed automatically.
- Identify the failed processing queue entry from the payment dashboard or KYC history.
- Confirm whether the failure was caused by:
- A T&C acceptance submission error — the BaaS provider did not accept the
Acknowledgedevent. - An EDD submission error — the BaaS provider returned an error or did not return an external EDD identifier.
- A T&C acceptance submission error — the BaaS provider did not accept the
- Correct the underlying issue (for example, re-present T&C disclosures to the account holder or contact the BaaS provider if the error is on their side).
- Re-initiate the KYC orchestration workflow for the account holder once the issue is resolved.
Important: Do not attempt to initiate KYC verification while a processing queue entry for the same account holder is in a failed or aborted state. Resolve the queue entry first to avoid duplicate or conflicting verification attempts.
Tips
- Check T&C acceptance before escalating KYC failures. Because T&C acceptance must complete before KYC is submitted, many KYC initiation failures trace back to a disclosure submission error rather than a problem with the identity verification itself. Always review the T&C record and EDD queue entry first.
- Use the KYC history audit trail. The
Pending/Initiatedhistory entry is created before the BaaS provider call. If this entry is missing, the orchestration did not reach the verification step — look for a failed or aborted processing queue entry earlier in the sequence. - Record the EDD external identifier for reference. When EDD submission succeeds, the BaaS provider returns an external identifier that is stored against the processing queue entry. Note this identifier when contacting the BaaS provider about a specific account holder's EDD submission.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| KYC verification was not submitted even though the account holder completed onboarding | T&C acceptance or EDD submission failed; the processing queue entry was aborted | Review the processing queue for a failed or aborted entry. Resolve the T&C or EDD issue, then re-initiate KYC orchestration. |
No KYC history entry with status Pending / Initiated exists for the account holder |
The orchestration did not reach the verification step | Confirm that T&C acceptance completed successfully and that no processing queue entry is in a failed state. |
| EDD external identifier is missing from the processing queue entry | EDD submission to the BaaS provider failed or the provider did not return an identifier | Check for a BaaS provider error on the EDD submission. Re-submit after resolving the error. |
| T&C acceptance timestamp is not recorded on the account holder's T&C record | The BaaS provider did not accept the Acknowledged event submission |
Verify that the disclosure data sent to the BaaS provider is complete and correctly formatted. Contact the BaaS provider if the error persists. |