HCM and payroll platforms

This guide is for human capital management (HCM) and payroll platforms that want to pay their clients' independent contractors through Wingspan. It covers how to model your clients and their contractors, how your pay-run objects map to Wingspan's, how money moves, and what to sync.

What you can offer through the V3 API

Capability	Where it lives
Contractor onboarding (tax information, payout method, requirements)	Payees and onboarding
One-off and batch contractor payments	Payables and payroll runs
Pay schedules	Payroll schedules
Contractor payout choices, including faster payout methods where available	Payout methods
Deductions from contractor pay	Deductions and credits
Contractor-side tax withholding account and debit cards	`/v3/finance/tax-withholdings` and `/v3/finance/cards`, on the contractor's own Account
Payments in currencies other than USD	`GET /v3/payments/currency/supported` lists the currencies you can use
Year-end 1099 filing	Tax filing

Insurance and benefits enrollment for contractors isn't available in the V3 API yet. Contact support if you need it.

Model your clients and their contractors

flowchart TD
  R[Your platform's root Account] --> C1[Client Account: Harbor Clinics]
  R --> C2[Client Account: Northwind Staffing]
  C1 --> P1[Payee: Priya Shah<br/>Contractor engagement]
  C2 --> P2[Payee: Luis Ortega<br/>Contractor engagement]
  P1 -.resolves to.-> K1[Priya's own Account<br/>payout methods, card, withholding]

Your platform has a root Account and a ServiceAccount credential that covers every descendant.
Each client that pays contractors is a child Account under your root, so payables, funding, and 1099s belong to the client, not to you.
Each contractor is a Payee owned by the client's Account, placed on a Contractor engagement. When the contractor claims their invite, the Payee links to the contractor's own Account, where their payout methods and any Wingspan financial products live.

Your backend acts on a client with X-Wingspan-Account: {clientAccountId}. Setup, credentials, and session details are in Embed Wingspan in your app.

Map your objects

HCM or payroll object	Wingspan object	Notes
Client company	Child Account	`externalId` = your client ID
1099 worker	Payee with `context: Contractor`, plus a PayeeEngagement with `engagementType: Contractor`	`externalId` = your worker ID
Worker's job or assignment	PayeeEngagement	Carries the onboarding requirements for that work
Pay schedule	PayrollSchedule	Separate schedules per run type
Contractor pay run	PayrollRun with `type: Contractor`	Its items are the payables selected into it
Earnings line	Payable line item	`description`, `totalCost` or `quantity` and `unitCost`
Deduction from pay	Deduction	See Deductions and credits
Payment made outside Wingspan	Payable marked paid off-platform	Counts toward 1099 totals without moving money

W-2 employees use a Payee with context: Employee and engagementType: Employee, which requires the payee's Account to have a principal Person. See Engagements.

How money moves

Wingspan-managed distribution. You create payables (or a contractor payroll run) on the client's Account. The client funds the payments, and Wingspan pays each contractor to the payout destination they chose. You don't send separate amounts to each destination.

sequenceDiagram
  participant HCM as Your platform
  participant WS as Wingspan
  participant C as Contractor
  HCM->>WS: Create payables or a Contractor payroll run (as the client)
  HCM->>WS: Finalize the run
  WS->>WS: Fund from the client's payment method
  WS->>C: Pay to the contractor's payout destination
  WS-->>HCM: Payable.Paid webhooks

Platform-managed distribution. If you already calculate splits and pay contractors on your own rails, you can still use Wingspan for onboarding and 1099s. Record each payment you made yourself as an off-platform payment (POST /v3/payments/payables/{payableId}/pay-off-platform) so year-end totals are complete.

What to sync

Direction	Trigger	Call or event
To Wingspan	New client	Create a child Account (needs a Person session; see Parent and child Accounts)
To Wingspan	New 1099 worker	`POST /v3/payments/payees` with `context: Contractor`, then `POST .../engagements` and `POST .../invite`
To Wingspan	Pay run approved	Create payables, then run or finalize the payroll run
From Wingspan	Worker ready to pay	Poll `paymentsEligibility` on the payee engagement. No webhook yet.
From Wingspan	Payment status	`Payable.Paid`, `Payable.PartiallyPaid`, `Payable.Returned`, and `FundsMovement.*` webhooks
From Wingspan	Run status	Poll `GET /v3/payments/payroll-runs/{payrollRunId}`. There are no payroll-run webhooks yet.

Roll out in waves

Start with a pilot group of clients and contractors in the staging environment, confirm payouts and onboarding end to end, then expand in waves while you watch payment failures and support volume. Contact us to plan the rollout.

Pitfalls

Paying from the platform's Account. Payables on your root Account make your platform the payer in Wingspan, including for year-end forms. Create them on the client's Account.
Using the ServiceAccount to create client Accounts. Account creation needs a Person session. Operate clients with the ServiceAccount afterward.
Reading Payable.Paid as funds received. It's Wingspan's internal state, not confirmation from the contractor's bank. See Paid vs DepositConfirmed.
Retrying a returned payment on the same payable. Returned is terminal. Create a new payable. See Refunds and returns.