Skip to main content
A benefits deduction reaches payroll as a line item: an ICHRA allowance, an HSA contribution, a voluntary premium. It goes through the employee payroll run endpoint, which also carries earnings and taxes.
Before you start
  • You’ve confirmed the integration supports this write - see Check write support.
  • You can generate a stable idempotency key per deduction - see Idempotency.

​
Steps

1

Fetch the schema

The response defines deductions as an array, with its own required array under items. It also says whether this connector expects integration_params - see Integration-specific fields.Result: The contract for this integration.
2

Read the customer's payroll codes

Each code carries code, name, and a type of EARNING or DEDUCTION. Filter to the deduction codes and use code as the value the write expects.Which code belongs to which benefit plan is the customer’s decision, so confirm the mapping with them and store it against the connector. An employer benefit also carries payroll_codes and deduction_code, which link a deduction line back to its plan by ID - see Reading benefits.Result: Codes that exist in this customer’s payroll configuration.
3

Build the body from the schema

The deduction body varies by provider. Workday takes a type and an id, ADP takes a code, and both take an amount. Build from the schema step 1 returned, and check the worked payload for the customer’s platform on Create Employee Payroll Run.Provider constraints live there too. Workday accepts one deduction per request and rejects a body carrying both earnings and deductions.Send amounts in the precision the schema specifies.Result: A body matching the contract for this platform.
4

Send with an idempotency key

Derive the key from the employee and the pay period, such as payroll-{employee_id}-{period_end}, so a retry reproduces it - see Idempotency.Result: The deduction is written.
5

Verify the period it landed in

Read the run back and confirm the period - see Get Employee Payroll Runs. The run carries start_date, end_date and check_date.Payroll systems close periods, and a write submitted after close can be applied to the next open one. The customer’s cut-off is not exposed through the API, so treat a late change as an adjustment in the following period.Result: Confirmation the amount sits in the period you intended.

​
Frequently Asked Questions

The code is absent from this customer’s configuration, or belongs to a different pay group. Read payroll codes for the connector and match against code, rather than reusing a value from another customer.
The retry carried a different X-Idempotency-Key, so Bindbee read it as a new write - see Idempotency. Correct the amount in the payroll system, then derive the key so the same deduction always produces the same value.
A payroll run carries start_date, end_date and check_date, and no plan year. Cross-reference the check date against the benefit’s coverage period - see Reading benefits.