Direct Payroll Integration

The direct payroll integration consists of two parts:

1. Payroll Events - This could be a partner provided webhook or a Basic Capital-provided API.
2. Partner-provided API endpoints - Endpoints that you as the partner need to provide that Basic Capital will call to retrieve detailed information from your payroll system as well as write contribution updates to.

You will need to provide us with webhooks that we can subscribe to to receive the following events:

• Employee updates
  • Basic Information
  • Employment status
• Payroll events

Note: If you do not have webhooks, Basic Capital can provision you a specific endpoint to call. Please see Payroll API for examples of what these endpoints will look like.

The specific API is up to you, as long as it provides endpoints to read the required information for employees and payroll events; and supports writing back deduction information for both employees and employers.

• Employee external ID : must match the ID used on pay statements; unmatched pay statements are dropped and will trigger an alert.
• Employment email
• Employment given name
• Employment surname
• Begin date
• Date of birth : age of ≥ 18 required for eligibility
• Compensation : only accepts USD, cadence needs to be MONTHLY/ANNUALLY/HOURLY/WEEKLY/COMMISSION/FIXED
• Employment status: default is full time
• Country code : only accepts USA
• End date : dates in the past will trigger termination workflow. required to terminate an employee in Basic’s systems.
• SSN
• Address : required for sending notices
• Personal email : required for invitation email

• Employer external ID : the HRIS ID for the employer
• Payment ID : the provider's payroll/payment id
• Pay date : contributions are scheduled on this date

Per-employee pay statement (Payroll Run)

• ID : equals the Payment ID
• Employee external ID : the employee's external ID exactly as sent in the census. Unmatched statements are dropped from processing and alerted
• Pay date
• Gross pay
• Deductions : needs to correspond to one of the following deduction types: traditional 401k, roth 401k, loan 401k, voluntary after tax 401k. A row of deduction data will be ignored if it does not contain a nonzero value for at least one of the applicable types.
• Pay period start / Pay period end
• Net pay
• Categorized earnings : { type, amount, name }. needed for scenarios where HRIS does not calculate the match (most common on Roth-only contributors) Eligible types: SALARY, WAGE, OVERTIME, DOUBLE_OVERTIME, BONUS, COMMISSION, TIPS, PTO, SICK. Excludes:REIMBURSEMENT and INCOME_1099 .
  • OTHER, SEVERANCE, UNKNOWN are ambiguous and park the event in PENDING_REVIEW unless the employer pre-declared them eligible. Without this field the basis is gross pay. Send typed earnings rather than one OTHER bucket

Deduction line (PayrollRunDeduction)

• Employee deduction type : processed types are TRADITIONAL_401K, ROTH_401K, AFTER_TAX_401K, LOAN_401K. Other enum values (IRAs, 403(b), 457, pension) are stored but not processed. The employer must have an offering configured for every type that appears or processing fails
• Employee deduction : absolute dollar amount withheld from paycheck. At most one LOAN_401K line per employee per statement
• Employer match : absolute dollar amount. Required when HRIS computes the match.

Basic Capital manages each employee's retirement deduction elections and pushes changes into your payroll system. To do that, we need the following from you:

• Per-employee deduction endpoints : we need endpoints to read, create, update and remove a deduction on an individual employee.
• A stable deduction ID : return an ID when a deduction is created, and include it when we read the employee back. We use it for later updates and removals.
• Deduction types:
  • Pre-tax 401(k)
  • Roth 401(k)
  • Voluntary after tax 401(k)
  • 401(k) loan repayment
• Amount formats:
  • A percentage of pay, which we send in basis points (300 = 3%).
  • A flat amount per paycheck, which we send in cents.
  • Contributions can be a percentage of pay or a flat amount. Loans are always fixed dollar amounts.
• Readable current state : the employee record should return all active deductions. We read it to confirm a write landed and to catch drift.

• Employer match settings : we need to set company-wide match rules which include the following features:
  • Tiered match
  • Non-elective match

Field names and payload shapes are flexible, and we'll adapt to your existing API. What matters is that your system can provide this data and allows us to write the appropriate deduction configurations.