Bacs payment files can now be imported directly into DDCMS Direct using our API, with no need to upload them manually in the UI. This allows you to automate your file submission process while still using the DDCMS Direct portal for validation, approvals, and scheduling.
Requirements
Before using the API, make sure you have:
DDCMS Direct enabled
A valid API key
Your client prefix
All API requests must include your API key in the request headers under the apiKey field, formatted as {apiKey}, to ensure successful authentication.
📌Note: If you need assistance locating or regenerating your API key, please reach out to our Access Digital Assistant. A member of the Support team will then provide the required details.
Import endpoint
Send a POST request using multipart/form-data:
Your request must include:
file – the Bacs payment file
fileType – the file format type
Supported file types:
bacs_standard_18 – Bacs Standard 18
bacs_standard_18_payment_lines – Standard 18 (payment‑line format)
smartdebit_direct_csv – SmartDebit Direct CSV format
bacs_active_eazipay – Bacs Active format (EaziPay)
The fileType determines which structural validation rules are applied. A successful response is only returned if the file passes the initial structural checks.
Successful import
If the file is accepted, the API returns the following information:
status – success
fileId – a unique UUID for the imported file
importedAt – timestamp of import
message – confirmation text
fileStatus – will be Queued for validation
nextSteps – guidance for what to do next in DDCMS Direct
Keep the fileId for future reference.
After file import
Once imported, the file will:
Appear in the Home screen
Appear in the Outgoing Files screen
Show Uploaded by: API User
Move into Queued for validation while full checks run
To support approval workflows, the Uploaded by name automatically transfers from API User to the first user who interacts with the file. This prevents users from approving files they effectively uploaded.
Attribution transfers when a user:
Sets the SUN
Sets the processing date
Sets the pay date
Selects approvers
Submits the file
Cancels the upload (e.g., duplicate)
📌Note: Attribution transfers once only and does not move again.
Error handling
The API may return different types of errors depending on the issue:
Error Code | When It Happens | Details |
400 – Something's not right with the request | The request is missing or contains invalid information | This may occur if the fileType is missing or invalid, the file is missing or empty, the request isn’t sent as multipart/form-data, or the file fails structural or format checks. When structural validation fails (status validation_failed), the response includes an errors array detailing the issues so you can correct them before re‑uploading. |
403 – Access not allowed | Your client doesn’t have DDCMS Direct enabled | The import endpoint cannot be used if the feature is disabled. |
413 – File too large | The uploaded file exceeds the size limit | The API accepts files up to a maximum size of 130 MB (137,000,000 bytes), and any file exceeding this limit will be rejected. |
500 – Something went wrong on our side | A server-side issue occurred | A general internal server error occurred. |