Developers

Payroll is a
POST request.

Create a company, add employees, run payroll, read the paystubs. Eight endpoints, eight webhooks and a sandbox where you can move time forward.

Request

POST /v1/payrolls

{

"company": "com_basil_7Hq2Lx",

"period": "2026-10-12..18",

"payday": "2026-10-23"

}

Response · 200

{

"id": "pr_01JB8K4M2Q",

"status": "approved",

"employees": 42,

"net": "36861.97",

"payday": "2026-10-23T06:00"

}

(01) One call

One request,
three ways to see it.

The JSON you get back, the paystub it prints, and the screen your customer’s employee opens.

curl

Node

Python

curl -X POST https://sandbox.payrun.test/v1/payrolls

-d company="com_basil_7Hq2Lx"

-d period="2026-10-12..18"

-d payday="2026-10-23"

-H "Payrun-Version: 2026-10-14"

200 OK · 412 ms

JSON

Paystub

In their app

{

"id": "pr_01JB8K4M2Q",

"status": "approved",

"employees": 42,

"gross": "48206.14",

"net": "36861.97",

"funds_debited": "52167.58",

"payday": "2026-10-23T06:00"

}

curl

Node

Python

curl -X POST https://sandbox.payrun.test/v1/payrolls

-d company="com_basil_7Hq2Lx"

-d period="2026-10-12..18"

-d payday="2026-10-23"

-H "Payrun-Version: 2026-10-14"

200 OK · 412 ms

JSON

Paystub

In their app

{

"id": "pr_01JB8K4M2Q",

"status": "approved",

"employees": 42,

"gross": "48206.14",

"net": "36861.97",

"funds_debited": "52167.58",

"payday": "2026-10-23T06:00"

}

(03) Sandbox clock

Skip to Friday
without waiting for Friday.

The sandbox keeps its own time. Move it to the next event and watch the webhooks your app would receive.

Pay run · week of Oct 12 · 42 employees

1 / 5

Cut-off · Tue, Oct 20, 17:00 ET

SANDBOX TIME · TUE, OCT 20, 17:00 ET

Webhook fired · payroll.approved

Advance to next event →

Pay run · week of Oct 12 · 42 employees

1 / 5

Cut-off · Tue, Oct 20, 17:00 ET

SANDBOX TIME · TUE, OCT 20, 17:00 ET

Webhook fired · payroll.approved

Advance to next event →

(04) Webhooks

Eight events,
one payload shape.

Pick an event to see what lands on your endpoint. Every payload is signed and retried for 72 hours.

payroll.approved

Your customer approved the run.

payroll.funded

The debit cleared at the partner bank.

payroll.funding_failed

The debit came back. Deposits are held.

paystub.issued

A paystub is ready for an employee.

deposit.returned

A bank returned one deposit.

tax_filing.submitted

A return left for the agency.

tax_filing.accepted

The agency accepted the return.

enrollment.updated

An employee changed a benefit.

POST your endpoint · payroll.approved

{ "type": "payroll.approved", "id": "evt_2prk", "data": { "payroll": "pr_01JB8K4M2Q", "approved_by": "Basil POS customer", "payday": "2026-10-23" }, "created": "2026-10-20T15:42:09-05:00" }

payroll.approved

Your customer approved the run.

payroll.funded

The debit cleared at the partner bank.

payroll.funding_failed

The debit came back. Deposits are held.

paystub.issued

A paystub is ready for an employee.

deposit.returned

A bank returned one deposit.

tax_filing.submitted

A return left for the agency.

tax_filing.accepted

The agency accepted the return.

enrollment.updated

An employee changed a benefit.

POST your endpoint · payroll.approved

{ "type": "payroll.approved", "id": "evt_2prk", "data": { "payroll": "pr_01JB8K4M2Q", "approved_by": "Basil POS customer", "payday": "2026-10-23" }, "created": "2026-10-20T15:42:09-05:00" }

Latest changes

Shipped this fall,
dated to the day.

2.15

Stipends that roll over

Wellness, remote and learning stipends can now carry unused amounts into the next month, up to a cap the employer sets.

2.14

Theme tokens now reach the PDF paystub

The color, font and logo of your theme now style the paystub employees download, not only the one on screen.

2.13

Off-cycle runs in one call

Bonuses, corrections and final paychecks now run through the same endpoint as regular payroll.

Keys today,

a test payroll by Friday.

Sandbox keys come with a seeded company, 42 employees and the clock above.

Keys today,

a test payroll by Friday.

Sandbox keys come with a seeded company, 42 employees and the clock above.

Create a free website with Framer, the website builder loved by startups, designers and agencies.