> ## 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. # Payment API overview > Generate BACS payment files — Standard 18, Barclays, Allica — for completed pay runs, retrieve them with time-limited download links, and manage each organisation's payment configuration. The Payment API turns a completed pay run into a BACS payment file you can upload to your bank. It generates and serves files in the Standard 18, Barclays (CSV or TXT), and Allica formats, manages each organisation's payment configuration — the source bank account, service user number, and file format — and lets you retry generation after fixing employees whose details failed BACS validation. Pay runs themselves are managed elsewhere; see [Running a pay run](/guides/pay-runs/running-a-pay-run). All endpoint paths on this page are relative to the service base path `/v1/payment`, appended to the gateway base URLs listed in the [API reference introduction](/api-reference/introduction). ## Key concepts * **Payment file** — the generated BACS file for one completed pay run, identified by its payroll configuration, tax year, pay frequency, and period. It carries a `status`, summary totals (records, employees, total amount), and a downloadable artefact with a time-limited `downloadUrl`. * **Payment file status** — the canonical outcome of generation: `GENERATED` (file produced for every employee), `PARTIAL_SUCCESS` (file produced for some, others need attention), `FAILED` (no file produced), `RETRYING` (a retry is in progress), or `SUBMITTED`. Always branch on this field, never on the HTTP status code. * **Affected employees** — when the status is `FAILED` or `PARTIAL_SUCCESS`, `failure.affectedEmployees` lists each employee blocking the file, with one validation issue per failed field. * **Payment format** — a (method, format, file format) combination such as BACS Standard 18 as `txt` or BACS Barclays as `txt` or `csv`. Each format advertises its `supportedFileFormats`; `fileFormat` defaults to `txt` when omitted. * **Payment configuration** — the per-organisation settings that drive file generation: the chosen method, format, and file format, plus the BACS source bank account (sort code, account number) and service user number. * **Payment reference** — an optional expression on the configuration that builds each file's reference from static text and tokens such as `{payDate}`, `{year}`, `{period}`, `{frequency}`, and separators. A `referenceDateFormat` enum (default `DMY_SLASH`) controls how date tokens render. ## API structure ### Payment files Fetch the file for a pay run with `GET /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}`. The response's `file` block is non-null when a downloadable artefact exists (`GENERATED`, `SUBMITTED`, `PARTIAL_SUCCESS`), and the `failure` block is non-null when employees were excluded (`FAILED`, `PARTIAL_SUCCESS`) — both appear together on a partial success. ### Retry Queue a regeneration with refreshed employee data using `POST /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}/retry`. The file must currently be `FAILED` or `PARTIAL_SUCCESS`; the retry is accepted asynchronously with a `202` and the status moves to `RETRYING` while it processes. ### Available payment configurations List the (method, format, file format) combinations an organisation can configure with `GET /available/config`. ### Organisation payment configuration Manage the configuration at `/config/{payrollConfigId}`: create it with `POST`, then read, replace, or remove it with `GET`, `PUT`, and `DELETE` on the same path. ## Typical workflow 1. Call `GET /available/config` to see which payment formats and file formats you can use. 2. Create the organisation's configuration with `POST /config/{payrollConfigId}`, supplying the method, format, BACS account details, and optionally a reference expression. 3. Complete a pay run in Flow Payroll — the service generates the payment file for it. 4. Fetch the file with `GET /file/run/{payrollConfigId}/year/{year}/frequency/{frequency}/period/{period}` and branch on `status`. 5. If the status is `FAILED` or `PARTIAL_SUCCESS`, correct the employees listed in `failure.affectedEmployees`, then queue a regeneration with `POST .../retry`. 6. Download the file from `file.downloadUrl` and upload it to your bank. ## Notes and best practices The `status` field in the 200 response body is the canonical outcome. Resource state is never reported through 4xx/5xx codes — a `500` means a server-side failure, not a failed file. * Download links expire at `file.downloadUrlExpiresAt`. Fetch the payment file again to obtain a fresh link. * Use `csv` as the `fileFormat` only when it appears in `supportedFileFormats` for the chosen method and format. * A retry against a file that is not `FAILED` or `PARTIAL_SUCCESS` is rejected with a `400`. * `createdBy` is `SYSTEM` for the first generation and `SYSTEM_REGEN` for automatic recovery regenerations, so you can tell how a file version came to exist. * `externalReference` is a forward-compatibility placeholder for future API-based payment flows and is always null today. ## Authentication Every request needs an `X-Auth-Token` header, and credentials with access to more than one organisation also send `X-Org-Id` — see [Authentication](/api-reference/authentication). Responses use the shared envelope described in [Response format](/api-reference/response-format).