Company Bank & Verification

This guide explains how to integrate with the Bank & Verification onboarding flows using only the public WEP API functions provided by the @worklio/wep package.

Overview

Before payroll can be enabled, two onboarding tracks must be completed in sequence.

1. Bank Setup: Operational banking, provider activation, and account verification.
2. Company Verification (KYC): Regulatory checks and documentation. This step can be started at any time, including alongside the bank setup process. However, if a bank provider is enabled (such as Kotapay or NatPay), the KYC cannot be submitted for review until bank setup is verified and completed.

Both tracks require a valid FEIN (Federal Employer Identification Number). Completion is determined by API data.

Prerequisites

If KYC is not enabled in your environment, you may skip the Company Verification flow.

High-Level Overview

Bank Setup

• Collect and display required bank account information.
• Create or update bank accounts using the provided API endpoints.
• If Plaid is available, complete Plaid verification for the account.
• If a bank provider is enabled, present and require signing the provider agreement; otherwise, skip this step.
• Confirm that all account and provider statuses are completed before proceeding to company verification.

Company Verification (KYC)

• Gather and display required business and ownership information.
• List and upload all required company and signatory documents.
• Save or update company KYC information.
• After all steps are complete, submit the KYC for review (only possible if bank setup is completed when a provider is enabled).
• Confirm that KYC status is completed before enabling payroll.

Step-by-Step Flow Outline

1. Ensure FEIN and companyId are available.
2. Begin Bank Setup: a. Fetch bank setup snapshot. b. Create/update bank accounts. c. If Plaid is available, request link token and complete Plaid flow. d. Collect company details as required by the bank provider. e. If a bank provider is enabled, present and sign the provider agreement document; otherwise, skip this step. f. Verify bank setup completion.
3. Begin Company Verification: a. Fetch KYC summary. b. List required documents. c. Upload documents. d. Save company KYC info. e. Submit KYC for review.
4. Once both tracks are completed, unlock payroll.

Step-by-Step Onboarding Flow

Bank Setup

Step 1: Display bank setup status and account fields

• Fields: Account type, routing number, account number, provider status, verification status
• API: wepGetBankSetup(companyId)

Step 2: Create or update the primary bank account

• Fields: Account type, routing number, account number
• API: wepCreateBankAccount(companyId) (for creation), wepUpdateBankAccount(companyId, accountId) (for update)

Step 3: If Plaid is available, request a link token and launch Plaid

• Fields: Plaid link token, Plaid UI
• API: wepGetPlaidLinkToken(companyId, accountId)

Step 4: Submit Plaid connection data

• Fields: publicToken, account metadata
• API: wepCreatePlaidConnection(companyId, accountId)

Step 5: Display and collect company details as required by the bank provider

• Fields: Company name, address, other provider-required info
• API: (provider-specific, e.g., wepGetBankProvider, wepUpdateBankProvider)

Step 6: If a bank provider is enabled, present the provider agreement document for review and signing; otherwise, skip this step

• Fields: Agreement document, signatory job title, full name, electronic consent (checkbox)
• API: wepSignBankProvider(companyId, accountId)

Step 7: Display completion status

• Fields: Account, verification, and provider statuses
• API: wepGetBankSetup(companyId)

Company Verification

Step 1: Display KYC summary and required fields

• Fields: Business name, FEIN, address, ownership info, KYC status
• API: wepGetCompanyKYC(companyId)

Step 2: List and review company KYC documents

• Fields: Document list, document status
• API: wepGetCompanyKYCDocuments(companyId)

Step 3: Retrieve signatories and their documents

• Fields: Signatory name, role, document status
• API: wepGetSignatories(companyId), wepGetSignatoryDocuments({ companyId, signatoryId })

Step 4: Get required document types for company and signatories

• Fields: Required document types
• API: wepGetCompanyKYCDocumentTypes({ companyId, documentScope })

Step 5: Upload required documents

• Fields: Document file upload, document type
• API: wepCreateCompanyKYCDocument(companyId)

Step 6: Save or update company KYC information

• Fields: Business info, ownership info
• API: wepSaveCompanyKYC(companyId)

Step 7: Submit company KYC for review

• Fields: Submission confirmation
• API: wepSaveCompanyKYC(companyId) (with submission flag or status)

Step 8: Display completion status

• Fields: KYC status, document status
• API: wepGetCompanyKYC(companyId), wepGetCompanyKYCDocuments(companyId)

API Reference

All functions require a companyId. For request/response details, refer to the official API typings.

Calling API Functions

API functions from @worklio/wep (such as wepGetCompanyKYC) do not make network requests directly. Instead, they return metadata describing how to construct the request, including:

• createRequestBody: Function to build the request body (if needed)
• method: HTTP method (e.g., 'GET', 'POST')
• url: Relative endpoint URL (e.g., companies/${companyId}/kyc)
• useResponseBody: Function to process the response body

To call the API, use the returned metadata with a standard HTTP client such as fetch():

const { method, url, createRequestBody, useResponseBody } =
  wepGetCompanyKYC(companyId);
const response = await fetch(`https://api.worklio.com/${url}`, {
  method,
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  // body: createRequestBody(data) if method is POST/PATCH
});
const result = useResponseBody(await response.json());

// createRequestBody example
const formData = new FormData();
formData.append("file", fileInput.files[0]);
const { createRequestBody } = wepCreateCompanyKYCDocument(companyId);
const body = createRequestBody(formData);

Refer to the API documentation or the @worklio/wep package for endpoint URLs, required parameters, and response handling.

Status & Enums

Error Handling & Edge Cases

• Plaid link tokens expire quickly; always request a fresh token before launching the Plaid flow.
• Only users with administrative privileges should attempt KYC or bank setup actions.
• Some providers may require additional fields or steps. Always check the provider type before proceeding.
• For partial failures in batched uploads, show per-file status and retry failed uploads.

Best Practices

• Handle API errors gracefully and provide user feedback.
• Use HTTPS for all API calls and never log or store sensitive tokens or documents.
• Batch document uploads to minimize network calls.
• Record timestamps and user actions for compliance and troubleshooting.

Completion Signals

Enable payroll only after:

1. Company Verification is completed.
2. Bank Setup reports completed status.

Record timestamps for both transitions for audit and analytics.

Quick Reference

Glossary

Additional Recommendations

• Authentication: Use secure tokens for all API requests.
• Obtaining companyId: Retrieve from your authentication context or company management flow.
• Document Upload Format: Use multipart/form-data for file uploads.
• Audit Logging: Track all onboarding actions and transitions for compliance.
• Versioning: Monitor API version changes and update integrations as needed.
• Checklist for Completion: Maintain a checklist to confirm all onboarding steps are complete.

References

• Plaid Link Documentation
• How to use WEP