Customer Accounts (Early Access)

Intro

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.

Customer Account Onboarding

Customer accounts are currently only available for integration via API.

Creating 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 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:

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"
}
'

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:

{
  "data": {
    "business_name": "Hooli",
    "code": "23",
    "company_id": "2139e98385ce9rer8583erer3048",
    "customer_account_id": "c7235er9eeedbfb6f1bf962da1a503",
    "partner_id": "c93488er943949fcejrer34350359",
    "status": "initial_onboarding"
  },
  "success": true,
  "testMode": false
}

Creating 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 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

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"
}
'

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 or
POST /customer-accounts/:{customerAccountID}/trigger-micro-deposits endpoint.

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"
}
'

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

curl --request POST \
     --url https://api.zeal.com/: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"
  ]
}
'

The Customer Account is now fully onboarded and ready to be mapped to worker 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 of the check that you are mapping to a customer account.

{
  "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
  }
}

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