> ## 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 payment file for a pay run ## OpenAPI ````yaml /api-reference/specs/payment.yaml get /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period} 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. - 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}: get: tags: - PaymentFile summary: Get payment file for a pay run operationId: getPaymentFileForPayRun parameters: - name: payrollConfigId in: path required: true schema: type: string - name: year in: path required: true schema: type: string - name: frequency in: path required: true schema: type: string - name: period in: path required: true schema: type: string responses: '200': description: >- Payment file retrieved successfully. The body always carries a `PaymentFileResponse` whose `status` field is the canonical outcome — GENERATED, PARTIAL_SUCCESS, FAILED, RETRYING, or SUBMITTED. Clients branch on `status`; do not infer state from HTTP code. `file` is non-null when a downloadable artefact exists (GENERATED, SUBMITTED, PARTIAL_SUCCESS); `failure` is non-null when employees were not included (FAILED, PARTIAL_SUCCESS). content: application/json: schema: allOf: - $ref: '#/components/schemas/ResponseBody' - type: object properties: content: type: object properties: data: $ref: '#/components/schemas/PaymentFileResponse' '404': description: No payment file exists for this pay run. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: >- Server-side failure (e.g. S3 regeneration broke). The resource state itself is never reported via 5xx — those go in the 200 body's `status` field. content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: ResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: type: object properties: data: type: object nullable: true metadata: type: object nullable: true properties: dateFormat: type: string default: yyyy-MM-dd dateTimeFormat: type: string default: yyyy-MM-ddTHH:mm:ss.fffZ paginationToken: type: string nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' messageToken: type: string PaymentFileResponse: type: object description: >- A generated BACS payment file for one pay run. Top-level fields are the resource identity (org/config/year/frequency/period), the status, and audit columns. Format, summary counts, the downloadable artefact, and failure context are grouped into nested objects. The `file` and `failure` blocks are independent — both may be present simultaneously when status is PARTIAL_SUCCESS (file was generated for some employees, others need attention). properties: organisationId: type: string example: ORG_DEV payrollConfigId: type: string example: 01JP0PM2QJ0XP31JPF9ZPD0RMC year: type: integer example: 2025 frequency: type: string example: Weekly period: type: integer example: 25 status: type: string enum: - GENERATED - SUBMITTED - PARTIAL_SUCCESS - FAILED - RETRYING description: >- Outcome state of the payment file. GENERATED: file produced for every employee. PARTIAL_SUCCESS: file produced for some, `failure.affectedEmployees` lists the rest. FAILED: no file produced. RETRYING: admin triggered a retry, processing in progress. example: GENERATED format: $ref: '#/components/schemas/PaymentFileFormatResponse' summary: $ref: '#/components/schemas/PaymentFileSummaryResponse' file: nullable: true description: >- The downloadable BACS file. Non-null when status is GENERATED, SUBMITTED, or PARTIAL_SUCCESS; null when no file exists (FAILED/RETRYING). allOf: - $ref: '#/components/schemas/PaymentFileArtefactResponse' failure: nullable: true description: >- Affected employees that need attention. Non-null when status is FAILED (every employee blocking the file) or PARTIAL_SUCCESS (employees not included in the generated file). Co-exists with `file` when status is PARTIAL_SUCCESS. allOf: - $ref: '#/components/schemas/PaymentFileFailureResponse' externalReference: type: string nullable: true description: >- Forward-compat placeholder for future API-based payment flows (e.g. Modulr batch ID, FasterPayments tracking id). Always null today because we only support BACS file generation. example: null createdDate: type: string format: date-time example: '2026-05-15T21:59:06+00:00' createdBy: type: string description: >- SYSTEM for first generation, SYSTEM_REGEN for auto-recovery regenerations. example: SYSTEM required: - organisationId - payrollConfigId - year - frequency - period - status - format - summary - createdDate - createdBy example: organisationId: 01K1BKF2MJC2WPNP38V3VVQ94C payrollConfigId: 01KMKX9ZBHS65ZWGV2266K0S8K year: 2025 frequency: Weekly period: 25 status: GENERATED format: paymentMethod: BACS paymentFormat: Standard18 summary: totalRecords: 15 employeeCount: 8 totalAmount: 6268.12 file: name: Acme_Ltd_Payment File 2025 Weekly 25 - 20260515-215906.txt size: 2279 downloadUrl: https://example.com/signed-url downloadUrlExpiresAt: '2026-05-22T21:59:06Z' failure: null externalReference: null createdDate: '2026-05-15T21:59:06+00:00' createdBy: SYSTEM MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' 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. 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 nullable: true items: $ref: '#/components/schemas/ValidationIssueArgument' PaymentFileFormatResponse: type: object description: Payment method/format combination this file was built for. properties: paymentMethod: type: string example: BACS paymentFormat: type: string example: Standard18 required: - paymentMethod - paymentFormat PaymentFileSummaryResponse: type: object description: >- Headline counts/totals so the UI can show 'paid N people' / 'M payment lines' without parsing the file. properties: totalRecords: type: integer 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 description: >- Distinct count of employees represented in the file. Operators see this as 'employees paid'. example: 8 totalAmount: type: number format: double description: Sum of every payment line in the file, in GBP. example: 6268.12 required: - totalRecords - employeeCount - totalAmount PaymentFileArtefactResponse: type: object description: >- The actual downloadable file. Frontends should fetch via `downloadUrl` directly; the URL expires at `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: Pre-signed download URL. Valid for ~7 days from issue. example: https://example.com/signed-url downloadUrlExpiresAt: type: string format: date-time description: >- When `downloadUrl` stops working. Re-fetch the resource to mint a fresh URL. example: '2026-05-22T21:59:06Z' required: - name - size - downloadUrl - downloadUrlExpiresAt 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). `summary` carries 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). properties: summary: $ref: '#/components/schemas/MessageWithTokenResponse' affectedEmployees: type: array 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.). items: $ref: '#/components/schemas/FailedEmployeeResponse' required: - summary ValidationIssueArgument: type: object properties: name: type: string value: type: string FailedEmployeeResponse: type: object description: >- One affected employee under `failure.affectedEmployees`. Frontend renders these as anchors to each employee's profile. properties: employeeId: type: string example: employee-001 employeeName: type: string example: Jane Doe issues: type: array 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. items: $ref: '#/components/schemas/ValidationIssue' required: - employeeId - employeeName - issues 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). ````