> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get the payment file history of a pay run > Needs permission payment:export. Every issue of the pay run's payment file, one entry per lock cycle, newest first. A pay run that was never unlocked has one entry. Nothing a lock produced is ever removed from the list: unlocking the pay run stamps the entry of the cycle it reopened (`unlock`), and locking it again adds the next cycle's entry and marks the earlier one `superseded`. Each entry carries its own signed download link, so the file that may have gone to the bank can be read beside the file the re-lock produced; a re-lock's entry also carries the `supplementary` file produced beside it, with its own link and the overpayments it found. A cycle whose file is no longer stored keeps its entry with no `file`: history is read, never regenerated. ## OpenAPI ````yaml /api-reference/specs/payment.json get /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}/history openapi: 3.0.3 info: title: FlowPayroll Payment API description: >- Payment Service API for FlowPayroll. Generates and serves BACS (Standard 18, Barclays CSV/TXT, Allica) payment files for completed pay runs, manages per-organisation payment configuration, and handles retry of failed payment-file generation. version: 0.1.0 servers: - url: https://api.sandbox.flowpayroll.ai/v1/payment security: - XAuthToken: [] XOrgId: [] tags: - name: PaymentFile description: >- Generated BACS payment file for a completed pay run. Status transitions: GENERATED | PARTIAL_SUCCESS | FAILED → (admin retries) RETRYING → GENERATED | PARTIAL_SUCCESS | FAILED. PARTIAL_SUCCESS means the file was generated for the employees that passed BACS validation AND `failure.affectedEmployees` lists the ones that need attention. When status is FAILED, no file was generated; `failure.affectedEmployees` lists every employee blocking the file. The UI can render affected employees with anchors to their profiles in both PARTIAL_SUCCESS and FAILED states. Locking the pay run again after an unlock produces the next lock cycle's full file (this resource) and, when the earlier cycle's file was in a ready status, a SUPPLEMENTARY file beside it on the history: the increases only, for an administrator who already sent the earlier file to the bank, to upload as a separate batch. The service never knows whether a file was sent, so it never deducts anything: every decrease is listed on the supplementary entry as an overpayment to recover by hand. - name: AvailablePaymentConfig description: >- List of BACS payment methods and formats available for an organisation to configure. - name: OrganisationPaymentConfig description: >- Per-organisation payment configuration. Stores the BACS source bank account, service user number, and which (method, format, file-format) combination drives payment file generation for that org's completed pay runs. paths: /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}/history: get: tags: - PaymentFile summary: Get the payment file history of a pay run description: >- Needs permission payment:export. Every issue of the pay run's payment file, one entry per lock cycle, newest first. A pay run that was never unlocked has one entry. Nothing a lock produced is ever removed from the list: unlocking the pay run stamps the entry of the cycle it reopened (`unlock`), and locking it again adds the next cycle's entry and marks the earlier one `superseded`. Each entry carries its own signed download link, so the file that may have gone to the bank can be read beside the file the re-lock produced; a re-lock's entry also carries the `supplementary` file produced beside it, with its own link and the overpayments it found. A cycle whose file is no longer stored keeps its entry with no `file`: history is read, never regenerated. operationId: getPaymentFileHistoryForPayRun parameters: - name: payrollConfigId in: path required: true schema: type: string description: The pay schedule (payroll configuration) the pay run belongs to. example: 01KMKX9ZBHS65ZWGV2266K0S8K - name: year in: path required: true schema: type: integer format: int32 description: >- The tax year the pay run is in, by the year it starts (2025 is 2025/26). example: 2025 - name: frequency in: path required: true schema: type: string description: >- How often the pay schedule pays, as it is named on the pay run (for example Weekly or Monthly). example: Weekly - name: period in: path required: true schema: type: integer format: int32 description: The pay period number within the tax year. example: 25 - $ref: '#/components/parameters/Request-Id' responses: '200': description: >- The history, newest cycle first. `currentLockCycle` is the cycle the payment file resource is on; each entry's `file` is null when that cycle produced no file or its file is no longer stored. content: application/json: schema: allOf: - $ref: '#/components/schemas/ResponseBody' - type: object properties: content: type: object properties: data: $ref: '#/components/schemas/PaymentFileHistoryResponse' metadata: $ref: '#/components/schemas/ContentMetadataResponse' '401': description: >- The access token is missing, expired or not valid (token `invalid_token`). Get a new token and send the request again. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '403': description: >- The caller lacks the permission in x-flow-permission (token `insufficient_permissions`), or cannot reach the organisation (token `access_denied`). content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '404': description: No payment file exists for this pay run. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: Something went wrong on our side. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '503': description: >- Access could not be checked just now. Retry after the seconds in Retry-After. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: parameters: Request-Id: name: Request-Id in: header required: false description: >- Optional. Your id for this request: it is carried into every log line about it, so quote it when you contact support. schema: type: string schemas: ResponseBody: type: object description: The envelope every answer is written in. required: - message properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' description: What happened, as text and as a token for translation. content: type: object required: - metadata properties: data: type: object nullable: true description: The data the operation answers with. metadata: $ref: '#/components/schemas/ContentMetadataResponse' description: How to read the dates in the data. nullable: true description: The answer's data and how to read it. Left out when there is none. validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true description: >- One entry per field the request got wrong. Left out when there are none. PaymentFileHistoryResponse: type: object description: >- Every issue of a pay run's payment file, one entry per lock cycle, newest first. A run that was never unlocked has one entry. Nothing a lock produced is ever removed from this list: an unlock stamps the entry of the cycle it reopened, and the re-lock adds the next cycle's entry and marks the earlier one superseded. required: - organisationId - payrollConfigId - year - frequency - period - currentLockCycle - cycles properties: organisationId: type: string description: The organisation the pay run belongs to. example: 01K1BKF2MJC2WPNP38V3VVQ94C payrollConfigId: type: string description: The pay schedule (payroll configuration) the pay run belongs to. example: 01KMKX9ZBHS65ZWGV2266K0S8K year: type: integer format: int32 description: The tax year of the pay run, by the year it starts. example: 2025 frequency: type: string description: How often the pay schedule pays. example: Weekly period: type: integer format: int32 description: The pay period number within the tax year. example: 25 currentLockCycle: type: integer format: int32 description: The cycle the current payment file resource is on. example: 2 cycles: type: array items: $ref: '#/components/schemas/PaymentFileCycleResponse' description: One entry per lock cycle, newest first. ContentMetadataResponse: type: object description: >- How to read the dates in the data, and the next page's token on a paged list. required: - dateFormat - dateTimeFormat properties: dateFormat: type: string description: The format of dates in the data. dateTimeFormat: type: string description: The format of timestamps in the data. paginationToken: type: string nullable: true description: The token for the next page, on a paged list that has one. MessageWithTokenResponse: type: object description: A message as text, and as a token with its arguments for translation. required: - text - token properties: text: type: string description: Default human-readable message. token: type: string description: >- Machine-readable message identifier (snake_case), for translation or your own wording. tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: Values the message refers to, by name. ValidationIssue: type: object description: >- Field validation item. `reasonToken` is a stable snake_case key for i18n or custom client messages; `reason` is the default English text from the API. required: - field - reason - reasonToken properties: field: type: string description: Dot-path of the field (e.g. name.firstName, address.line1). reason: type: string description: Default human-readable message. reasonToken: type: string description: Machine-readable error identifier (snake_case). reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: Values the reason refers to, by name. PaymentFileCycleResponse: type: object description: >- One lock cycle's full payment file, as it was when that cycle was current, and the supplementary file produced beside it on a re-lock. required: - lockCycle - status - format - summary - generatedDate - createdBy - superseded - replacedFiles properties: lockCycle: type: integer format: int32 description: >- The lock cycle this entry is for: 1 for the first lock, n + 1 for each re-lock after an unlock. example: 1 status: type: string enum: - GENERATED - PARTIAL_SUCCESS - SUBMITTED - QUEUED - FAILED - RETRYING - REBUILDING - GENERATING - UNKNOWN - NOT_REQUIRED description: >- As `status` on the payment file resource. A superseded cycle keeps the status it had; nothing records whether its file went to the bank. example: GENERATED trigger: type: string enum: - payroll_run_completed - retry - regeneration - relock - supplementary - rebuild - generate - null nullable: true description: >- What produced the file: payroll_run_completed, retry, regeneration, relock, supplementary or rebuild. Null on an entry written before triggers were recorded. example: payroll_run_completed format: $ref: '#/components/schemas/PaymentFileFormatResponse' description: Payment method and format the file was built for. summary: $ref: '#/components/schemas/PaymentFileSummaryResponse' description: Headline counts and totals of the cycle's file. file: $ref: '#/components/schemas/PaymentFileArtefactResponse' nullable: true description: >- The cycle's file with its own signed link, valid for one hour. Null when the cycle produced no file, or its file is no longer stored. failure: $ref: '#/components/schemas/PaymentFileFailureResponse' nullable: true description: >- The employees the cycle's file left out, as on the payment file resource; null when none. generatedDate: type: string format: date-time description: When the cycle's file was generated. example: '2026-05-15T21:59:06+00:00' createdBy: type: string description: >- SYSTEM for the first file, SYSTEM_REGEN when the file was produced again automatically, or the administrator who rebuilt it. example: SYSTEM supersedes: type: integer format: int32 nullable: true description: The cycle whose file this one replaced; null for a first issue. superseded: type: boolean description: True once a later cycle's file replaced this one. example: false supersededOnLockCycle: type: integer format: int32 nullable: true description: >- The cycle whose file replaced this one; null while it is the current file. supersededDate: type: string format: date-time nullable: true description: >- When a later cycle's file replaced this one; null while it is the current file. unlock: $ref: '#/components/schemas/PaymentFileUnlockResponse' nullable: true description: >- The unlock that reopened this cycle; null while the cycle has not been unlocked. supplementary: $ref: '#/components/schemas/PaymentFileSupplementaryResponse' nullable: true description: >- The supplementary file produced beside this cycle's full file, for an administrator who had already sent the earlier cycle's file to the bank (docs/evolution/0008). Null for cycle 1, and for any cycle whose re-lock found no earlier file in a ready status. replacedFiles: type: array items: $ref: '#/components/schemas/PaymentFileReplacedResponse' description: >- The files this cycle's file replaced when an administrator rebuilt it with the current payment settings, newest first, each with its own signed link. Same payments, earlier bank or file type. Empty when the file was never rebuilt. ValidationIssueArgument: type: object description: A named value a message refers to. required: - name properties: name: type: string description: The argument's name. value: oneOf: - type: string - type: number - type: boolean - type: array items: type: string nullable: true description: >- The argument's value: text, a number, true or false, or a list of text. PaymentFileFormatResponse: type: object description: Payment method/format combination this file was built for. required: - paymentMethod - paymentFormat properties: paymentMethod: type: string description: Payment method. example: BACS paymentFormat: type: string description: Payment format within the method. example: Standard18 PaymentFileSummaryResponse: type: object description: >- Headline counts/totals so the UI can show 'paid N people' / 'M payment lines' without parsing the file. required: - totalRecords - employeeCount - totalAmount properties: totalRecords: type: integer format: int32 description: >- Number of payment lines in the file. A multi-account employee contributes one line per destination account, so this is >= employeeCount. example: 15 employeeCount: type: integer format: int32 description: >- Distinct count of employees represented in the file. Operators see this as 'employees paid'. example: 8 totalAmount: type: number format: decimal description: Sum of every payment line in the file, in GBP. example: 6268.12 PaymentFileArtefactResponse: type: object description: >- The file to download. Fetch `downloadUrl` directly, without the auth header; it stops working at `downloadUrlExpiresAt`. required: - name - size - downloadUrl - downloadUrlExpiresAt properties: name: type: string description: >- User-visible filename (basename only). The frontend uses this for the download attachment name. example: Acme_Ltd_Payment File 2025 Weekly 25 - 20260515-215906.txt size: type: integer format: int64 description: File size in bytes. example: 2279 downloadUrl: type: string format: uri description: >- Signed download link on the files address, valid for one hour from issue. The file downloads under `name`. Re-fetch this resource for a fresh link. example: https://files.flowpayroll.ai/files/payment/signed-link downloadUrlExpiresAt: type: string format: date-time description: >- When `downloadUrl` stops working. Re-fetch the resource for a fresh link. example: '2026-05-15T22:59:06Z' PaymentFileFailureResponse: type: object description: >- Employees that did not make it into the BACS file. Set on both FAILED (the whole run is blocked) and PARTIAL_SUCCESS (the file was generated for everyone else). required: - summary properties: summary: $ref: '#/components/schemas/MessageWithTokenResponse' description: >- The i18n-ready message: its `token` is one of `paymentFileGenerationFailed`, `paymentFileBlockedByInvalidEmployeeData` (FAILED with per-employee causes) or `paymentFilePartiallyGenerated` (PARTIAL_SUCCESS, with `succeededCount` and `failedCount` token arguments). affectedEmployees: type: array items: $ref: '#/components/schemas/FailedEmployeeResponse' nullable: true description: >- Per-employee failure detail when the failure can be attributed to specific employees. Null when the failure is org-wide (missing payment config, etc.). PaymentFileUnlockResponse: type: object description: The unlock stamped on a cycle's payment file. required: - scope properties: unlockedDate: type: string format: date-time nullable: true description: When the pay run was unlocked. example: '2026-10-26T10:15:00+00:00' reason: type: string nullable: true description: >- The reason given for the unlock, as the person who unlocked it wrote it. example: Overtime missed scope: type: string enum: - Full - Employees description: Full, or Employees when only the listed employees were reopened. example: Full employeeIds: type: array items: type: string nullable: true description: The reopened employees of a partial unlock; null for a full one. PaymentFileSupplementaryResponse: type: object description: >- A cycle's supplementary payment file: the increases since the earlier cycle's file, one line per employee whose net pay went up on the re-lock, to upload as a separate batch when that file has already gone to the bank (if it has not, upload the cycle's full file instead and ignore this one). The overpayments are every decrease the re-lock found, information only: the service cannot know whether the earlier file was sent, so it never deducts them from a later payslip. The administrator recovers them by hand. required: - status - totalRecords - totalAmount - supplementaryOfLockCycle - paidLeaverEmployeeIds - overpayments - replacedFiles properties: status: type: string enum: - GENERATED - PARTIAL_SUCCESS - SUBMITTED - QUEUED - FAILED - RETRYING - REBUILDING - GENERATING - UNKNOWN - NOT_REQUIRED description: >- GENERATED: a file of every increase. PARTIAL_SUCCESS: a file of the increases that passed BACS validation. FAILED: no file could be produced; retry the payment file. NOT_REQUIRED: no employee's net pay increased, so there is no file; the overpayments, if any, are still listed. example: GENERATED file: $ref: '#/components/schemas/PaymentFileArtefactResponse' nullable: true description: >- The supplementary file with its own signed link, valid for one hour. Null when there is none (NOT_REQUIRED, FAILED), or its file is no longer stored. totalRecords: type: integer format: int32 description: Payment lines in the file, one per increased line. example: 1 totalAmount: type: number format: decimal description: The sum of the increases, in GBP. example: 420 supplementaryOfLockCycle: type: integer format: int32 description: The lock cycle whose file this one tops up. example: 1 paidLeaverEmployeeIds: type: array items: type: string description: >- Employees paid by the file who have left: confirm their bank details before uploading it. Empty when none. overpayments: type: array items: $ref: '#/components/schemas/PaymentOverpaymentResponse' description: >- Every employee whose lines went down against the earlier cycle's file, one entry per employee per reason. Empty when none. replacedFiles: type: array items: $ref: '#/components/schemas/PaymentFileReplacedResponse' description: >- The supplementary files a rebuild of this cycle replaced, newest first, each with its own signed link. Empty when never rebuilt. PaymentFileReplacedResponse: type: object required: - status - format - generatedDate - replacedDate - replacedBy properties: status: type: string description: >- The status the file had when it was replaced: GENERATED or PARTIAL_SUCCESS. example: GENERATED format: $ref: '#/components/schemas/PaymentFileFormatResponse' description: Payment method and format the replaced file was built for. file: $ref: '#/components/schemas/PaymentFileArtefactResponse' nullable: true description: >- The replaced file with its own signed link, valid for one hour. Null when it is no longer stored. generatedDate: type: string format: date-time description: When the replaced file was generated. example: '2026-05-15T21:59:06+00:00' replacedDate: type: string format: date-time description: When the administrator asked for the rebuild that replaced it. example: '2026-05-16T09:12:40+00:00' replacedBy: type: string description: Who asked for the rebuild. example: USER#01K1BKF2MJC2WPNP38V3VVQ94D FailedEmployeeResponse: type: object description: >- One affected employee under `failure.affectedEmployees`. Frontend renders these as anchors to each employee's profile. required: - employeeId - employeeName - issues properties: employeeId: type: string description: The employee. example: employee-001 employeeName: type: string description: The employee's name. example: Jane Doe issues: type: array items: $ref: '#/components/schemas/ValidationIssue' description: >- One ValidationIssue per failed field. Same shape used across the platform for 400-response `validationIssues`, so frontends can use a single i18n key lookup for both. PaymentOverpaymentResponse: type: object description: >- Money the earlier cycle's file paid that the re-lock no longer owes. Information only: the service never deducts it from a later payslip, because it cannot know whether the earlier file was ever sent to the bank. required: - employeeId - employeeName - amount - reason properties: employeeId: type: string description: The employee whose lines went down. example: employee-001 employeeName: type: string description: The employee's name. example: Jane Doe amount: type: number format: decimal description: The overpaid amount in GBP, always positive. example: 180 reason: type: string enum: - employee - leaver - third_party description: >- employee: the employee's own net pay went down. leaver: as employee, for someone who has left and has no next pay run. third_party: a line paid to a third party (a court order payee, a deduction) went down; the payee, not the employee, was overpaid. example: employee securitySchemes: XAuthToken: type: apiKey in: header name: X-Auth-Token description: Access token obtained from OAuth2 client credentials flow XOrgId: type: apiKey in: header name: X-Org-Id description: >- Organisation to scope the request to. Required when the principal can access more than one organisation; optional for single-organisation principals (the authorizer resolves it automatically). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.