Field validation

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.

Machine-readable: JSON Schema · OpenAPI

Identity#

paymentIdstringRequired

Your identifier for the payment record.

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

companystringRequired

Company code issued by the PayCaptain team.

Rule: Must match your PayCaptain company code exactly.
Example: "ABC"

hrEmployeeIdstringRequired

The person being paid.

Rule: Must match an employee already sent to PayCaptain.
Example: "9876543210"

payrollCodestringRequired

The employment the payment belongs to.

Rule: Must match that person's active employment.
Example: "123"

Payment#

payCodestringRequired

Pay Code for this pay element.

Rule: Must match a Pay Code Name configured in PayCaptain.
Example: "Bonus"

datestringRequired

Date of the payment.

Format: YYYY-MM-DD
Example: "2026-11-28"

unitsnumberRequired

Quantity, for example hours.

Example: 1

ratenumberRequired

Rate per unit.

Example: 250

descriptionstringOptional

Text shown on the payslip.

Example: "Quarterly bonus"

informationstringOptional

Extra detail shown behind the help icon on the payslip.

Example: "Q3 performance bonus"

archivedbooleanOptional

Archive the payment so it is not paid.

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

Cost allocation#

locationstringOptional

Location worked.

Example: "Baker Street"

departmentstringOptional

Department worked.

Example: "Marketing"

teamstringOptional

Team worked.

Example: "Content"

jobstringOptional

Job worked.

Example: "Content Marketing"

Minimal valid record#

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