> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Accounts (Early Access)

> The concept of a Customer Account represents the end-client of a staffing company. Typically staffing companies act like marketplaces, supplying labor to brands who provide work opportunities. Zeal's customer accounts functionality enables staffing companies to map labor and payroll fees to their end-customers. Debits and credits are processed completely on Zeal's payment rails.

**Note:** Customer Accounts is an early access feature. Please contact your Zeal team for more information on this feature

## In this guide

* Which endpoints are needed to integrate with and onboard Customer Accounts.
* A step by step explanation of the onboarding steps.
* Mapping customer accounts to worker checks.

***

## API

Customer accounts are currently only available for integration via **API**.

### Create a Customer Account

The first step of the customer account onboarding process is the creation of customer accounts. Customer account creation is facilitated via the [Create Customer Account ](/reference/customer-accounts/create-customer-account)or POST `/customer-accounts` endpoint. The endpoint requires the following body parameters:

* `code`: A unique custom-set code to associate with the customer account
* `companyID`: The ID of the Zeal company
* `business_name`: The business name of the customer account/end-client

Below is an example of a POST `/customer-accounts` cURL request:

<CodeGroup>
  ```bash bash theme={null}
  curl --request POST \
       --url https://api.zeal.com/customer-accounts \
       --header 'Authorization: <API KEY>' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --data '
  {
    "code": "23",
    "companyID": "2139e98385ce9rer8583erer3048",
    "business_name": "Hooli"
  }
  '
  ```
</CodeGroup>

The endpoints response will return a newly created `customer_account_id`, the unique Zeal identifier for the customer account. The response will also contain a `status` flag indicating the current status of the customer account, upon first creation - this status will be marked as `initial_onboarding`. Below is an example response from the customer account creation request:

<CodeGroup>
  ```bash bash theme={null}
  {
    "data": {
      "business_name": "Hooli",
      "code": "23",
      "company_id": "2139e98385ce9rer8583erer3048",
      "customer_account_id": "c7235er9eeedbfb6f1bf962da1a503",
      "partner_id": "c93488er943949fcejrer34350359",
      "status": "initial_onboarding"
    },
    "success": true,
    "testMode": false
  }
  ```
</CodeGroup>

### Create a Funding Source

The next step of of customer account onboarding is the creation and attachment of a funding source to the newly created customer account. This is accomplished by utilizing the [Create Funding Source](https://dash.readme.com/project/zeal-docs/v1.0/refs/create-funding-source) or POST `/customer-accounts/:{id}/funding-sources`. Similar to creating a bank account for an employee or company within Zeal, the endpoint requires the body parameters of:

* `account_number`: The account number of the bank account
* `routing_number`: The routing number of the bank account
* `account_type`: Type of the bank account (checkings, savings)
* `companyID`: The ID of the Zeal company
* `customerAccountID`: the ID of the customer account

<CodeGroup>
  ```bash bash theme={null}
  curl --request POST \
       --url https://api.zeal.com/customer-accounts/:id/funding-sources \
       --header 'Authorization: Bearer <API KEY>' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --data '
  {
    "account_type": "checking",
    "customerAccountID": "c7235er9eeedbfb6f1bf962da1a503",
    "account_number": "12345",
    "routing_number": "12345",
    "companyID": "2139e98385ce9rer8583erer3048"
  }
  '
  ```
</CodeGroup>

### Trigger and Verify Microdeposits

In order to verify the bank account and funding source of the customer account, Zeal utilizes microdeposit verification. Microdeposits are triggered and these values appear on the bank account within 1-3 days as originating from the Zeal company. These values are then passed for verification in order to verify the funding source/account.

To **trigger** microdeposits for a funding source, pass the [Trigger Microdeposits](https://dash.readme.com/project/zeal-docs/v1.0/refs/trigger-ca-microdeposits) or POST `/customer-accounts/:{customerAccountID}/trigger-micro-deposits` endpoint.

<CodeGroup>
  ```bash bash theme={null}
  curl --request POST \
       --url https://api.zeal.com/customer-accounts/:c7235er9eeedbfb6f1bf962da1a503/trigger-micro-deposits \
       --header 'Authorization: Bearer <API KEY>' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --data '
  {
    "companyID": "2139e98385ce9rer8583erer3048"
  }
  '
  ```
</CodeGroup>

To **verify** microdeposits after the values appear in the funding source account, pass the [Verify Microdeposits](/reference/customer-accounts/verify-microdeposits) or POST `/customer-accounts/:{customerAccountID}/verify-micro-deposits` endpoint.

<CodeGroup>
  ```bash bash theme={null}
  curl --request POST \
       --url https://api.zeal.com/customer-accounts/:c7235er9eeedbfb6f1bf962da1a503/verify-micro-deposits \
       --header 'Authorization: Bearer <API KEY>' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --data '
  {
    "companyID": "2139e98385ce9rer8583erer3048",
    "deposits": [
      "2",
      "1.3"
    ]
  }
  '
  ```
</CodeGroup>

The Customer Account is now fully onboarded and ready to be mapped to worker payments.

## White-Label

### Create a Customer Account

Currently, creating a customer account is only supported in the API. Refer to the [API guide](/docs/customer-accounts-closed-beta#create-a-customer-account) to create a Customer Account.

### Onboarding Flow

Call [Generate Customer Account Onboarding Link](/reference/customer-accounts/generate-customer-account-onboarding-link). This returns a link to the white-label component. You can select if you want the customer account to go through the full onboarding flow - profile information and funding source, or one of the steps.

<CodeGroup>
  ```bash bash theme={null}
  curl --request POST \
       --url 'https://api.zeal.com/customer-accounts/onboard' \
       --header 'Accept: application/json' \
       --header 'Authorization: Bearer {{testApiKey}}' \
       --header 'content-type: application/json' \
       --data '
  {
    "companyID": "{{companyID}}",
    "customerAccountID": "{{customerAccountID}}",
    "profileInfo": true,
    "bankInfo": true
  }
  '
  ```
</CodeGroup>

Give the employer access to the link.

When the customer account accesses the link, they see the white-label component on your domain with your logo. First, the customer account completes the **Profile Information** section.

<img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/50d28e1adce02e2e1accbe771d4e9836ea0a3fa9f134ce79fae6f1b45a24ea91-Screenshot_2024-10-02_at_2.47.37_PM.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=e1829cf40a1a2ccea3035232ed8293d9" alt="" width="4028" height="2642" data-path="images/docs/50d28e1adce02e2e1accbe771d4e9836ea0a3fa9f134ce79fae6f1b45a24ea91-Screenshot_2024-10-02_at_2.47.37_PM.png" />

Next, the customer account completes the **Bank Linking**. This step has two options -

1. Instant bank verification (Early Access) - Zeal uses **Teller** to securely connect to the customer account's bank account. We collect basic information, including account number and routing number.
2. Microdeposits - This option requires a micro-deposit flow where two small deposits are made to the customer account's bank account. The customer account will leave the onboarding flow and return later to confirm the deposit amount. The micro-deposit flow generally takes 1 - 3 days.

<img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/484a36148babfdd5b6218541738c7837d6549a4bb22ea7d72d668a6afb0e0f91-Screenshot_2024-10-02_at_2.50.38_PM.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=20e19fac9ec3b29feda6c32abf9a2d60" alt="" width="4026" height="2628" data-path="images/docs/484a36148babfdd5b6218541738c7837d6549a4bb22ea7d72d668a6afb0e0f91-Screenshot_2024-10-02_at_2.50.38_PM.png" />

Once a verified bank account has been linked to the customer account, they should be able to start making payments.

## Mapping Customer Accounts to Payments

Customer Accounts can be attached to checks in order to accurately map labor and payroll fees as well as to map disbursed funds from the end-client accounts to the respective workers. To do so, a `customerAccountID` can simply be passed in the [Shift Object](/reference/employee-checks/shifts/shift-object) of the check that you are mapping to a customer account.

<CodeGroup>
  ```bash bash theme={null}
  {
    "shiftID": "4712c99283304b7b989179aae36b4590",
    "status": "pending",
    "employeeID": "1234567890",
    "customerAccountID": "c7235er9eeedbfb6f1bf962da1a503", //the Customer Account ID
    "employeeCheckID": "1098876345",
    "first_name": "erlich",
    "last_name": "bachman",
    "metadata": {},
    "time": "2023-04-15T14:00:00Z",
    "wcc_code": "12324",
    "hourly": {
      "hours": 8,
      "wage": 20,
      "custom_name": "custom hourly"
    },
    "overtime": {
      "hours": 2,
      "wage": 30
    },
    "reimbursement": {
      "amount": 8.5
    }
  }
  ```
</CodeGroup>

## Recap

* A customer account is created and onboarded via the API
* Funding sources are attached to customer accounts and require microdeposit verification
* Customer accounts can be mapped to payments by passing the customerAccountID in the respective check's shift object