Skip to main content
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. 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.

​
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. Responses use the shared envelope described in Response format.