Payroll & Tax Withholding
Atomic multi-party splits for employee compensation and tax compliance.
Payroll & Tax Withholding
Processing payroll involves more than just paying an employee. A single "Gross Salary" must be split into multiple destinations: the employee's net pay, income tax for the government, social security contributions, and benefit providers.
Using Beetles' Linked Transfers, you can ensure that either the entire payroll event succeeds or nothing happens at all.
Architecture
We use a single "Treasury" source and multiple destination accounts across different ledgers (or the same ledger) to handle the split.
The Payroll Lifecycle
Defining the Split
A $5,000 Gross Salary might be split as follows:
- Net Pay: $3,800 (Employee)
- Income Tax: $700 (Government)
- Social Security: $300 (Pension Fund)
- Health Care: $200 (Insurance Provider)
Executing the Atomic Split
We send all four transfers as a single linked chain. If the corporate treasury has only $4,999, the entire payroll fails, ensuring no partial payments are made.
curl -X POST http://localhost:8080/v1/transfers
-d '{
"transfers": [
{
"debit_account_id": "TREASURY_ID",
"credit_account_id": "EMPLOYEE_NET_ID",
"amount": 380000,
"linked": true
},
{
"debit_account_id": "TREASURY_ID",
"credit_account_id": "IRS_TAX_ID",
"amount": 70000,
"linked": true
},
{
"debit_account_id": "TREASURY_ID",
"credit_account_id": "PENSION_FUND_ID",
"amount": 30000,
"linked": true
},
{
"debit_account_id": "TREASURY_ID",
"credit_account_id": "HEALTH_INSURANCE_ID",
"amount": 20000,
"linked": false
}
]
}'Advanced Payroll Scenarios
1. Bonuses & Performance Commissions
Bonuses are handled as additional linked transfers in the bundle. You can use Metadata to flag them for tax purposes differently than the base salary.
# Transfer 1: Base Salary ($3,800)
# Transfer 2: Commission ($500)
# Transfer 3: Combined Tax ($850)2. Multi-Currency Payroll & International Tax
If you pay an employee in USDT but must pay the local government in BRL, you use the /v1/exchanges endpoint for the tax leg of the split.
Beetles ensures the exchange rate is locked and the BRL is minted/credited to the government ledger at the exact same moment the USDT is debited from your treasury.
Advantages of this Model
- Guaranteed Compliance: You can't accidentally pay the employee without also setting aside the tax. The ledger enforces this at the engine level.
- Simplified Reconciliation: Every payroll event is a single "bundle" of transfers. Auditing the
gross_salary_id(via metadata) reveals the complete breakdown instantly. - Real-time Liability Tracking: The government's account shows exactly how much tax has been withheld across the entire company, updated in real-time as each employee is paid.
The "Linked" Flag: Note that the last transfer in the bundle must have "linked": false. This signals the engine that the atomic chain is complete.
Cross-Ledger Splits: If taxes must be paid in a different currency/ledger than the salary, use the /v1/exchanges endpoint instead of /v1/transfers for that specific leg of the split.