Batch file naming and structure

Naming

Batch request file

The file name for each batch request file must be unique. To be accepted for further processing, a batch request file name must comply with the following format: 

[Submission Platform]_[File Sequence Number]_[FileType].csv
  • Submission Platform is the unique identifier for the server you use to submit batch files to Adyen.
    This is especially important if you have multiple servers submitting files, and find it difficult to keep track of the sequence number across the servers.
  • File Sequence Number is the file submission number. It must always increment by exactly one unit after each successful file submission.
    File sequence numbers correlate with the submission platform, i.e. the server from where the files originate.
    The Adyen payments platform rejects batch files when:
    • The batch file submission number, i.e. the file sequence number, has already been used;
    • The system detects a gap in the number sequence because adjacent numbers are not consecutive. For example: 201 followed by 203.
  • FileType defines the type of transactions/requests that the file contains.
    Allowed values:

Batch result file

The file name for each batch result file complies with the following format:

Non-encrypted
batch result file
[Submission Platform]_[File Sequence Number]_[FileType].csv_result
Encrypted
batch result file
[Submission Platform]_[File Sequence Number]_[FileType].csv_result_enc

The batch request file undergoes a series of validation checks at line item level, and then the batch result file is posted to the result folder on the SFTP.

Batch acknowledgment file 

The file name for each batch acknowledgment file complies with the following format:

[Submission Platform]_[File Sequence Number]_[FileType].csv_ack

The batch request file undergoes a series of validation checks at line item level. If any error occurs during the process, the batch acknowledgment file is posted to the ack folder on the SFTP.

Structure

The batch file should be delivered in CSV (Comma Separated Values) format, as per RFC 4180, with the following exceptions:

  • Multi-line fields are not allowed;
  • It is allowed to have a variable number of fields per line. 
The file needs to have a file header and a file trailer to allow parsing.
If either file header or file trailer is missing, it is not possible to top parse the file, and the process returns one or more errors.

The batch file has the following structure:

The file must conform to the following parameters:

  • File sequence number: the file header ([FH]) contains a file sequence number that must match the file sequence number in the file name.
  • File types: the batch file can contain only one of the allowed file types identifying the type of transaction that processes.
    It is not allowed to mix file types/transaction types in the same file. i.e. it is not possible to specify more than one file type/transaction type per batch file.
  • File encoding: the batch file should be encoded using UTF-8.
  • Column counts: Some lines in the file contain optional fields.
    While the number of fields per line may vary depending on the specified transaction type, the column count per transaction type is fixed.
    For example, File Header field 9 is an optional field. However, if you do not use it, you need in any case to insert a delimiter as a placeholder.
  • Character set: the character set used to represent text data needs to be Unicode.