What's New

If you have the DDCMS Direct feature enabled, you can now import BACS files programmatically via the API, without needing to log in to the DDCMS Direct UI to upload them.

Prerequisites

Before using the API import endpoint, please ensure the following:

• Your client account has the DDCMS Direct feature enabled.

• You have a valid API key for your client (provided by the onboarding or support team).

• You know your client prefix (provided in your welcome email).

Authentication

All requests must be authenticated using an API key, passed as a header in your request:

• apiKey: {apiKey}

How to Import a File

Send a POST request to the following endpoint:

POST https://ddcms.accesspaysuite.com/api/v3/client/{clientPrefix}/ddcmsdirect/import

The request must be sent as multipart/form-data and must include both of the following fields:

Field	Type	Required	Description
file	File	Yes	The BACS payment file to be imported.
fileType	String	Yes	The file format type. Must be one of the supported values listed below.

Supported File Types

You must specify the file type of the file you are uploading. This determines which structural validation rules are applied. The following values are accepted for the fileType parameter:

fileType Value	Description
bacs_standard_18	BACS Standard 18
bacs_standard_18_payment_lines	BACS Standard 18 Payment Lines
smartdebit_direct_csv	SmartDebit Direct CSV
bacs_active_eazipay	BACS Active (EaziPay)

Successful Import Response

If your file passes initial structural validation, the API returns a 200 OK response containing the following fields:

Field	Description
status	Returns `success` when the file has been imported successfully.
fileId	A unique UUID assigned to your imported file — save this for future reference.
importedAt	The date and time at which the file was imported.
message	A human-readable message confirming the import.
fileStatus	The current status of the file. Will be `Queued for validation` on a successful import.
nextSteps	Guidance on what to do next — directing you to the DDCMS Direct UI to review validation results and complete any required actions, such as SUN assignment or processing date selection.

Example response:

json

{
  "status": "success",
  "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "importedAt": "2024-01-20T15:30:00Z",
  "message": "File imported successfully",
  "fileStatus": "Queued for validation",
  "nextSteps": "File is queued for validation. Check DDCMS Direct UI for validation results and any required actions such as SUN assignment or processing date selection."
}

What Happens After a Successful Import

Once your file has been imported via the API, it will appear in the DDCMS Direct UI (Outgoing Files screen and Home screen) with an "Uploaded by: API User" attribution. The file will be in Queued for validation status while the system runs full validation checks.

When a file is uploaded via the API, it is initially attributed to API User. To ensure the approval workflow functions correctly - specifically to prevent a user from approving their own upload - the attribution automatically transfers to the first user that interacts with the file in the DDCMS Direct UI.

The "Uploaded by" attribution transfers once, to whichever user is the first to interact with the file. It transfers at the point that user performs any one of the following actions:

• Setting the SUN

• Setting the processing date

• Setting the pay date

• Selecting approvers

• Submitting the file

• Explicitly cancelling the upload (e.g if file is a duplicate)

Once attribution has transferred to that user, it does not transfer again. From that point, the approval workflow will correctly prevent that user from approving the file themselves, in line with your client's approval configuration.

Error Responses

If there is a problem with your request, the API will return an appropriate error response. The table below summarises the possible error scenarios:

HTTP Status	Scenario	status Value
400	Missing fileType parameter	error
400	Invalid fileType value	error
400	Missing or empty file	error
400	Request not sent as multipart/form-data	error
400	File fails structural/format validation	validation_failed
403	DDCMS Direct feature not enabled for your client	error
413	File exceeds the maximum allowed size of 130 MB (137,000,000 bytes)	error
500	Internal server error	error

When a file fails structural validation (status validation_failed), the response includes an errors array with detailed descriptions of the specific structural issues found in the file, helping you identify and correct the problem before re-uploading.

API Documentation

The full API specification for this endpoint, including all parameters, request/response schemas, and response samples, will be added to the DDCMS API Specification upon deployment:

https://api-docs-ddcms-v3.accesspaysuite.com/