Batch acknowledgement file

We describe the fields included in the batch acknowledgment (ACK) file.

After validating the submitted batch request file, an ACK file generates:

  • If the batch request file successfully passes the validation check, the ACK file provides a report overview of the processed data.
  • If one or more lines in the requested file do not pass the validation check, they are included in the generated ACK file so you can review them.

ACK - Validation successful

After receiving a batch request file, the Adyen payments platform carries out a series of validation checks. If all validation checks are successful, a batch acknowledgment (ACK) file generates and returns with the fields described below.

Sample ACK - Validation successful
FH,1.0,TEST,Company,TestCompany,CaptureOverAuthAmount,1,ws@Company.TestCompany,Modification,EchoData_BatchAck
R,2,8
N,NextFileSubmissionNumber,2

File Header [FH]

The File Header [FH] record marks the start of the ACK file.

Field #

Format

Description

1

Fixed value: FH

Record type identifier.

2

Numeric [0-9]+

Version number.
This field enables version control for the release of future enhancements for batch processing.

3

Allowed values:
  • TEST
  • LIVE

It specifies the environment: either test or live/production.

4

Fixed value: Company

Account type.

5

Alphabetic data [A-Z, a-z]

Specifies the company account name.

6

Alphabetic data [A-Z, a-z]

Submission platform.
The value specified in the file should match the corresponding value in the file name.

7

Numeric [0-9]+

File sequence number.
The value specified in the file should match the corresponding value in the file name.

8

Alphabetic data [A-Z, a-z]

The WS user name specified to connect to the Adyen SOAP service.

9

Allowed values:

  • Authorisation
  • Payout
  • RefundWithData
  • Modification
  • PayoutModification
  • AccountUpdater

File type.
Defines the type of transactions that are submitted for further processing.

10

Alphabetic data [A-Z, a-z]

EchoData

In this field you can specify any data you may want to be returned with the result file.
When this field is populated, its content is returned exactly as is.
The Adyen payments platform does not use this data.

Maximum character length: 80 characters.

Record Line [R]

The File Trailer record specifies the number of blocks and lines in the ACK file.

Field #

Format

Description

1

Fixed value: R

Record type identifier.

2

Numeric [0-9]+

Number of processed blocks.

3
Numeric [0-9]+

Number of processed line records.

Next File Submission Number [N]

This line specifies the number of the next file to process in a batch submission sequence . File sequence numbers are associa ted with the submission platform the files originate from, and they sequentially increment by one unit after each successful file submission.

The NextFileSubmissionNumber sub-line is always included in an ACK file, regardless of the file validation outcome:

  • When a file in a batch process is submitted successfully and without errors, the submission number for the next file in the process increases sequentially.

  • When a file in a batch process contains errors, the system tries to guess the submission number for the next file in the sequence. Therefore, this value may be incorrect.

A correct file in a batch submission process satisfies the following minimum requirements:

  • The file name adheres to the naming conventions for batch acknowledgement files (ACK).

  • The file data matches the expected data type and format.

The submission number is always incorrect when it is not possible to read or parse the header of a file. This can happen in the following cases:

  • The file sequence number is missing or it is incorrectly formatted in the file name.

  • The submission platform name is missing or it is incorrectly formatted in the file name.

  • A database exception might occur during file insertion.

Field #

Format

Description

1

Fixed value: N

Record type identifier

2

Fixed value: NextFileSubmissionNumber

Record content definition.

3

Numeric [0-9]+

The number corresponding to the next expected file in the submission sequence.

ACK - Validation failed

When one or more validation errors occur, an error line gets generated per line in the requested file that did not pass validation.

Sample ACK - Validation failed
E,L,5,5000,Invalid Merchant Account 
E,L,6,5000,Invalid Merchant Account 
N,NextFileSubmissionNumber,2

Error Line [E]

The File Header record contains marks the start of the ACK file.

Field #

Format

Description

1

Fixed value: E

Record type identifier

2

Allowed values:

  • FH
  • L
  • SL
  • F

The record type where the error occurred:

  • FH: the error occurred in the file header.
  • L: the error occurred in a line record.
  • SL: the error occurred in a sub-line record.
  • F: the error occurred as the file was incomplete or unreadable.

3

Numeric [0-9]+

The file line number where the error occurred.

4

Numeric [0-9]+

The error code associated with the error.

5

Alphabetic data [A-Z, a-z]

The error description.

Next File Submission Number [N]

This line specifies the number of the next file to process in a batch submission sequence . File sequence numbers are associa ted with the submission platform the files originate from, and they sequentially increment by one unit after each successful file submission.

The NextFileSubmissionNumber sub-line is always included in an ACK file, regardless of the file validation outcome:

  • When a file in a batch process is submitted successfully and without errors, the submission number for the next file in the process increases sequentially.

  • When a file in a batch process contains errors, the system tries to guess the submission number for the next file in the sequence. Therefore, this value may be incorrect.

A correct file in a batch submission process satisfies the following minimum requirements:

  • The file name adheres to the naming conventions for batch acknowledgement files (ACK).

  • The file data matches the expected data type and format.

The submission number is always incorrect when it is not possible to read or parse the header of a file. This can happen in the following cases:

  • The file sequence number is missing or it is incorrectly formatted in the file name.

  • The submission platform name is missing or it is incorrectly formatted in the file name.

  • A database exception might occur during file insertion.

Field #

Format

Description

1

Fixed value: N

Record type identifier

2

Fixed value: NextFileSubmissionNumber

Record content definition.

3

Numeric [0-9]+

The number corresponding to the next expected file in the submission sequence.