Direct Debit

DDCMS Direct File Import

Import BACS payment files via the API for processing through DDCMS Direct. The client must have the DDCMS Direct feature enabled.

POST/client/{clientCode}/ddcmsdirect/importImports a BACS payment file via the API for processing through DDCMS Direct#
description:

Imports a file into DDCMS Direct for processing through the existing approval workflows. The file undergoes initial structural validation based on the specified fileType. If validation passes, the file is stored and queued for further validation. Prerequisites:

authorization:ApiKeyAuth
content-type: multipart/form-data
path parameters:
shared schema directDebit/path/client
{
  • clientCode
    string (≤ 6 chars)MandatoryThe client code provided in your welcome email.
}
request body:
{
  • file
    string (binary upload)MandatoryThe file to be imported. Must be in one of the supported formats: BACS Standard 18, BACS Standard 18 Payment Lines, SmartDebit Direct CSV, or BACS Active (EaziPay).
  • fileType
    stringMandatoryPossible values: bacs_standard_18, bacs_standard_18_payment_lines, smartdebit_direct_csv, bacs_active_eazipayThe file format type, which determines which structural validation rules are applied to the uploaded file. Must be one of the following values: - bacsstandard18 - BACS Standard 18 - bacsstandard18paymentlines - BACS Standard 18 Payment Lines - smartdebitdirectcsv - SmartDebit Direct CSV - bacsactiveeazipay - BACS Active (EaziPay)
}

Responses

200OK
response body:
{
  • status
    stringReturns success when the file has been imported.
  • fileId
    string (guid)The unique idenitifer assigned to the imported file. You should save this for future reference.
  • importedAt
    string (date-time)The date/time at which the file was imported.
  • message
    stringA human-readable message confirming the import.
  • fileStatus
    stringThe current status of the file. Will be Queued for validation on a successful import.
  • nextSteps
    stringGuidance on what to do next after a successful import.
}
400Bad Request
response body:
{
  • status
    stringReturns error for parameter issues, or validation_failed for structural validation features.
  • message
    stringA human-readable description of the error.
  • errorType
    stringOnly present when status is validation_failed. Returns structural.
  • supportedFileTypes
    arrayOnly present when the error is caused by an invalid fileType value. Lists the supported file type keys.
}
403Forbidden
response body:
{
  • status
    string
  • message
    string
}
413Payload Too Large
response body:
{
  • status
    string
  • message
    string
  • maxFileSizeBytes
    integerThe maximum file size allowed, in bytes (137000000).
}
500Internal Server Error
response body:
{
  • status
    string
  • message
    string
}
Example request
Endpoint
POST /client/{clientCode}/ddcmsdirect/import
Request body
# multipart/form-data — use -F flags with cURL
fileType=bacs_standard_18
file=@/path/to/your/file.txt
cURL
curl -L -g -X POST \
  'https://ddcms.accesspaysuite.com/api/v3/client/{clientCode}/ddcmsdirect/import' \
  -H 'apiKey: {apiKey}' \
  -F 'file=@/path/to/payment-file.txt' \
  -F 'fileType=bacs_standard_18'
Response
HTTP/1.1 200 OK

{
  "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."
}
HTTP/1.1 400 Bad Request

"error"
HTTP/1.1 403 Forbidden

{
  "status": "error",
  "message": "DDCMS Direct feature not enabled for this client"
}
HTTP/1.1 413 Payload Too Large

{
  "status": "error",
  "message": "File exceeds the maximum allowed size",
  "maxFileSizeBytes": 137000000
}
HTTP/1.1 500 Internal Server Error

{
  "status": "error",
  "message": "An internal server error occurred"
}

Prerequisites

  • The client must have the DDCMS Direct feature enabled.
  • The request must be sent as multipart/form-data.
  • Both file and fileType form fields are required.

Upload attribution

Files uploaded via this endpoint are recorded as “Uploaded by: API User”, and appear in the DDCMS Direct UI and on the home screen with that attribution. When a user subsequently interacts with the file, the attribution transfers to that user so that approval workflows stay correct.

After a successful import

The file will have status “Queued for validation”. Check the DDCMS Direct UI for validation results and any required actions, such as SUN assignment or processing date selection.