> ## 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. # Create the payment file of a locked pay run that has none > Needs permission payment:export. For a pay run that locked before its pay schedule had payment settings, so no payment file was produced. Once the settings exist, this builds the file from the payments stored when the pay run locked, with those settings, without unlocking the pay run. The build runs in the background: `status` is GENERATING until it ends GENERATED, PARTIAL_SUCCESS or FAILED, and the outcome is announced as a payment file event with trigger `generate`. A pay run that already has a payment file is rebuilt or retried instead. ## OpenAPI ````yaml /api-reference/specs/payment.json post /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}/generate 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}/generate: post: tags: - PaymentFile summary: Create the payment file of a locked pay run that has none description: >- Needs permission payment:export. For a pay run that locked before its pay schedule had payment settings, so no payment file was produced. Once the settings exist, this builds the file from the payments stored when the pay run locked, with those settings, without unlocking the pay run. The build runs in the background: `status` is GENERATING until it ends GENERATED, PARTIAL_SUCCESS or FAILED, and the outcome is announced as a payment file event with trigger `generate`. A pay run that already has a payment file is rebuilt or retried instead. operationId: generatePaymentFile 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: '202': description: The file is being created; the payment file is GENERATING. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '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: The pay run does not exist. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '409': description: >- The file cannot be created: the pay run already has one, is not locked, was locked again after a correction, has no payments stored, or the payment settings are missing or incomplete. The message says which. 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. 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. 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. 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. 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. 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.