# Payment fields

> Every field accepted by POST /payment, with its validation rule.

A payment is a pay element such as a bonus, expense or deduction. Send one JSON object per pay element to `POST /payment`. To withdraw a payment, [archive it](https://developer.paycaptain.com/rules#archiving).

Machine-readable: [JSON Schema](https://developer.paycaptain.com/schemas/payment.schema.json) · [OpenAPI](https://developer.paycaptain.com/openapi.json)

## Identity

### `paymentId`

Your identifier for the payment record.

- Type: string
- Required
- Rule: Unique in your system. Resubmitting the same paymentId updates the record.
- Example: `"PM-000912"`

### `company`

Company code issued by the PayCaptain team.

- Type: string
- Required
- Rule: Must match your PayCaptain company code exactly.
- Example: `"ABC"`

### `hrEmployeeId`

The person being paid.

- Type: string
- Required
- Rule: Must match an employee already sent to PayCaptain.
- Example: `"9876543210"`

### `payrollCode`

The employment the payment belongs to.

- Type: string
- Required
- Rule: Must match that person's active employment.
- Example: `"123"`

## Payment

### `payCode`

Pay Code for this pay element.

- Type: string
- Required
- Rule: Must match a Pay Code Name configured in PayCaptain.
- Example: `"Bonus"`

### `date`

Date of the payment.

- Type: string
- Required
- Format: YYYY-MM-DD
- Example: `"2026-11-28"`

### `units`

Quantity, for example hours.

- Type: number
- Required
- Example: `1`

### `rate`

Rate per unit.

- Type: number
- Required
- Example: `250`

### `description`

Text shown on the payslip.

- Type: string
- Optional
- Example: `"Quarterly bonus"`

### `information`

Extra detail shown behind the help icon on the payslip.

- Type: string
- Optional
- Example: `"Q3 performance bonus"`

### `archived`

Archive the payment so it is not paid.

- Type: boolean
- Optional
- Rule: Send true with the same paymentId to remove the payment from payroll. Records are archived, never deleted.
- Default: `false`
- Example: `false`

## Cost allocation

### `location`

Location worked.

- Type: string
- Optional
- Example: `"Baker Street"`

### `department`

Department worked.

- Type: string
- Optional
- Example: `"Marketing"`

### `team`

Team worked.

- Type: string
- Optional
- Example: `"Content"`

### `job`

Job worked.

- Type: string
- Optional
- Example: `"Content Marketing"`


## Minimal valid record

```json
{
  "paymentId": "PM-000912",
  "company": "ABC",
  "hrEmployeeId": "9876543210",
  "payrollCode": "123",
  "payCode": "Bonus",
  "date": "2026-11-28",
  "units": 1,
  "rate": 250
}
```