# Pay Run programs: approve, pay, prepare, void

URL: /code/mcp/pay-run/verbs · Id: `page:code/mcp/pay-run/verbs`

> The Pay Run Verbs approve, pay, prepare, void as MCP do programs, with inputs, result, refusals and an example.

Reference for [Pay Run](/business/nouns/pay-run), one group of [Pay Run programs](/code/mcp/pay-run).

### PayRun.approve
Approve accepts a prepared Pay Run within the approver’s Mandate, books its cost, and schedules payment to land on the pay date. [Verb page](/business/nouns/pay-run/approve?interface=mcp).

```text
do: return await $.PayRun.approve(input)
```

Emits [`PayRun.approved`](/business/events/PayRun.approved).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The approved Pay Run, scheduled for its pay date. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.approve({ payRun: 'payrun_hqqWu5rAyZ' })"
  }
}
```

### PayRun.pay
Pay funds an approved Pay Run: net pay to each employee’s bank on the pay date, taxes and deductions to the payroll provider. [Verb page](/business/nouns/pay-run/pay?interface=mcp).

```text
do: return await $.PayRun.pay(input)
```

Emits [`PayRun.paid`](/business/events/PayRun.paid).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The approved Pay Run. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The paid Pay Run. |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The funding Transaction. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.pay({ payRun: 'payrun_hqqWu5rAyZ' })"
  }
}
```

### PayRun.prepare
Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval. [Verb page](/business/nouns/pay-run/prepare?interface=mcp).

```text
do: return await $.PayRun.prepare(input)
```

Emits [`PayRun.prepared`](/business/events/PayRun.prepared).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `company` | [Company](/business/nouns/company) | Yes | The employer Company. |
| `periodStart` | `date` | Yes | The first day of the pay period. |
| `periodEnd` | `date` | Yes | The last day of the pay period. |
| `payDate` | `date` | Yes | The day net pay should land. |
| `kind` | `string` | No | Defaults to `regular`; `offCycle` pays outside the schedule. |
| `humans` | list of [Human](/business/nouns/human) | No | Only these employees. Defaults to every employee of the Company. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run, with every amount per employee. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.prepare({ company: 'company_28zYNZEno0', periodStart: '2026-10-22', periodEnd: '2026-10-22', payDate: '2026-10-22' })"
  }
}
```

### PayRun.void
Void sets aside a prepared Pay Run that is wrong, so a corrected one can be prepared; the record stays. [Verb page](/business/nouns/pay-run/void?interface=mcp).

```text
do: return await $.PayRun.void(input)
```

Emits [`PayRun.voided`](/business/events/PayRun.voided).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The prepared Pay Run. |
| `reason` | `text` | Yes | Why it was set aside. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `payRun` | [Pay Run](/business/nouns/pay-run) | Yes | The voided Pay Run. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.void({ payRun: 'payrun_hqqWu5rAyZ', reason: 'Example reason' })"
  }
}
```