1 File selection
2 Alias Files
   2.1 Upload file
   2.2 Format check
   2.3 Process file
3 Other Files
   3.1 Upload file
   3.2 Format check
   3.3 Process file
4 File download
   4.1 Electronic reporting
5 File validation statuses

1 File selection

From your Ingenico ePayments account, click Operations > Batch Manager to upload the payment files. You have the option of uploading "Alias" files or "Other files" (such as: Transaction and Subscription files).

The files you upload must be plain text files that have a certain file format which can be generated using any application (e.g. MS Access, MS Excel etc.).

If you don't have an application to create these formatted transaction files, you can create these files manually by typing each transaction line (max. 30,000 lines or 7 MB). However, to ensure that your files get processed swiftly, we recommend you limit each file to 2,500 lines.

We have created an MS Excel file to help you create formatted transaction files for uploading. This MS Excel spreadsheet integrates a macro which will allow you to create a simple text file containing all the information in the spreadsheet.

It is not the spreadsheet itself which you have to upload, but the text file you create via the macro in the MS Excel spreadsheet.

Respect the following rules when preparing the transaction files:

  • The files must be ASCII files
  • One line per order (excepted for headers and/or footers), lines separated by the Carriage Return and Line Feed character pair (ASCII: 13 10 – HEX: 0xD 0xA)
  • The fields must be separated by a “;”
  • The fields themselves cannot contain any “;”

A standard batch file has the following transaction layout:

Field #FieldDescription
1 AMOUNT Amount to be paid MULTIPLIED BY 100, as the amount format must not contain any decimals or other separators
2 CURRENCY ISO alpha order currency code, e.g. EUR, USD, GBP, CHF, etc.

Note: To ensure optimal processing of your batch files, all currencies configured in your Ingenico ePayments account under Configuration > Account > Currency should be configured accordingly per payment method used (Configuration > Payment methods > Contract data).
3 BRAND Card brand (“Direct Debits NL” for Direct Debits NL or similar information for other payment methods)
4 CARDNO Card/account number (a bank account number should always have 10 digits: if the account has less than 10 digits, complete with zeroes on the left. For PostBank accounts: “000” + 7 digits or “P00” + 7 digits.)
5 ED Expiry date (MM/YY or MMYY) (99/99 or 9999 for Direct Debits NL)
6 ORDERID Your unique order reference (merchant reference)
7 COM Order description
8 CN Customer name
9 PAYID Our system’s unique transaction reference
10 OPERATION

The payment procedure you have configured in the "Global transaction parameters" tab, in the "Default operation code" section of the Technical Information page will define your default transaction operation. When you send an operation value in the batch Operation field, this will overwrite the default value.

Please refer to the Parameter Cookbook for the possible values.

11 AUTHORIZATION CODE Authorisation code, not received via our system.
12 AUTHORIZATION MODE The way the authorisation code in field 11 was received. Possible value: ‘TEL’ for telephone
13 AUTHORIZATION DATE The date/time when the authorisation code in field 11 was received. (MM/DD/YY HH:MM:SS)
14 PSPID Your affiliation name in our system
15 GLOBORDERID Reference grouping several orders together, allows you to subsequently request a group maintenance operation on these transactions.
... Blank fields ...
22 OWNERADDRESS Customer’s street name and number
23 OWNERZIP Customer’s postcode
24 OWNERTOWN Customer’s town/city name
25 OWNERCTY Customer’s country
26 OWNERTELNO Customer’s telephone number
27 CVC Card Verification Code
... Blank fields ...
35 ECI

Electronic Commerce Indicator. You can configure a default ECI value in the "Global transaction parameters" tab, in the "Default ECI value" section of the Technical Information page. When you send an ECI value in the batch ECI field, this will overwrite the default ECI value.

Possible (numeric) values:

0 - Swiped
1 - Manually keyed (MOTO, card not present)
2 - Recurring payments, originating from MOTO
3 - Instalment payments
7 - E-commerce with SSL encryption
9 - Recurring after first e-commerce transaction

... Blank fields ...


The following parameters are relevant within the scope of the Credential-on-File guideline (COF) by the payment schemes Visa / MasterCard. Detailed information on their usage can be found in dedicated chapter Alias creation and usage within Credential-on-File guideline (COF).

Field #

Field

Description
52 COF_INITIATOR* Values:

CIT - A transaction initiated by a cardholder
MIT - A transaction initiated by a merchant
53 COF_TRANSACTION* Values:

FIRST - First of a series of transactions
SUBSEQ - Subsequent series of transactions
54 COF_SCHEDULE* Values:

SCHED - A scheduled transaction
UNSCHED - An unscheduled transaction
55 Blank field ...
56 COF_RECURRING_EXPIRY* currently available in TEST only
End date : date of the last scheduled payment of a series
Values:

YYYYMMDD (i.e. 20190914)
57 COF_RECURRING_FREQUENCY* currently available in TEST only
Days between payments for a scheduled series.
Values:

numeric between 2 and 4 digits (i.e. 31, 031 or 0031)
* Please send the parameter values according to the format as defined in the table. Otherwise the transaction will be blocked by our system.

Note: you can also optionally send additional fields if you have activated certain options/functionalities in your Ingenico ePayments account. Check the documentation of the option for more information on the related additional fields.

You can have the following file transaction codes:

  • ATR: code for new transactions
  • MTR: code for maintenance operations on existing transactions.

Any file you upload is automatically an ATR file unless you specify otherwise in the file header.

Headers and footers:

  • OHL: login information (not necessary when performing a manual file upload).
  • OHF: header containing the general file parameters (only necessary when the transaction code is MTR). Format: OHF;Merchant’s file reference;Transaction code (ATR/MTR);Operation;Number of orders.
  • OTF: general file footer, specified at the end of the file (only necessary when there’s a header in the file).

For more information, go to Advanced Batch

Examples:

ATR file
OHF;File20070430;ATR;;3;
1000;EUR;;4111111111111111;11/02;Order0001;;Paul Smith;
100;EUR;;4111111111111111;11/02;Order0002;; Bill Durand;
2032;EUR;;4111111111111111;11/02;Order0003;;John Doe;
OTF;

(or)

1000;EUR;;4111111111111111;11/02;Order0001;;Paul Smith;
100;EUR;;4111111111111111;11/02;Order0002;; Bill Durand;
2032;EUR;;4111111111111111;11/02;Order0003;;John Doe;

MTR file
OHF;Filename;MTR;SAS;1;
1000;EUR;;;;;;;1280281;
OTF;

2 Alias Files

2.1 Upload file

To upload "Alias" files:

  1. Click “Upload new batch file"
  2. Click "Alias" and "Select File".
  3. Select the file you want to upload from your computer. You will be redirected back to the Batch Manager page where the selected file is being checked. A counter and a progress bar are displayed to inform you of the time left to launch the file processing stage.
  4. Click “Process” to process the file. A progress bar informs you of the progress. For more information about validation statuses, please refer to Chapter 6: File validation statuses.

Note:

  • Due to PCI DSS reason, you have 60-minutes to process the file. Your only option is to delete the file once the 60-minutes are up.
  • If you accidentally select to upload an Alias file that is already in the list of processed Alias file, a message pops up to inform you of the existing uploaded file and asks if you would like to continue. Click "Yes" to continue with the upload, or "No" to cancel the file upload

If you don't launch the process within an hour, the status changes to “Expired”. In this case, you need to re-upload the files a second time. You can also clear the file from the Batch table. If a file is successfully processed, "Processed" is displayed under Status/Progress.

2.2 Format check

After you have uploaded the Alias file, we will first check its format. We shall validate if the file layout content format are correct. We do not store the transactions in our database at this stage, so you can still delete the file if necessary. The Alias file is always set in Asynchronous mode (ASYNC) and is auto-refreshed throughout the format check.

The result of the format check can be any of the following statuses:

Status Description Actions
Invalid All lines of the file are incorrect Delete
Valid All lines of the file are parsed with success and can be processed Delete; Process
Partially valid Only part of the file is valid and can be processed. The number of correct lines is displayed next to the status Delete; Process

The actions you can perform are depending on the file status. When the status is “Invalid”, you can only delete the file. You will not be able to continue with the file processing either.
To learn more about the result of the format check click the icon for more information. The following describes the expanded list and table:

Header Row

Item Description
Reference A reference number assigned by the platform
File name
The name of the file submitted by the merchant
Upload date
The date of the file upload
Status/Progress The status of the format check. There are three statuses: Valid, Partially valid, and invalid. A progress bar displays the validating progress.
Action The action you can perform based on the statuses

File Summary

Item Description
Total operation
The total number of lines in the Alias file
Incorrect operations
The number of lines that are invalid and will not be processed
Correct operations
The number of lines that are valid and that can be processed
Uploaded by
Person who uploaded the Alias file
NCMODE
The submission mode: Automatic File Upload (AFU) or Manual File Upload (MFU)
Upload date
Timestamp of the file upload

Error Description

(Displays only when the file is partially valid or invalid)
Item Description
Error description
The description of the error
Error lines
The location of the error in the Alias file

Operation Details

A list of operation code names and the number of line with the operation(s).

2.3 Process file

Once the Alias file is checked for its format and returns either with a “Valid” or “Partially valid” status, it enters the file processing stage.

To start the file process:

  1. Click "Process" under "Actions".
  2. A pop-up message opens and presents the option to either process the file or not by clicking on “Yes” (process the file) or “No” (do not process the file).

When the file is processed, the status will be updated to “Processed”. Next to it displays a fraction that applies to the successfully processed or partially processed Alias file. For example:

  • For a successfully processed Alias files, a fraction displays 10/10 under “Status/Progress”. This means that 10 lines out of the total 10 lines in the Alias file were successfully processed.
  • For partially processed Alias file, the fraction displays 5/10 under “Status/Progress”. The fraction interprets that 5 lines out of the 10 lines in the transaction file were successfully processed.

To learn more about the result of the processed Alias file, click theicon for more information. The following describes the parts of this expanded list and table:

Header Row

Item Description
Reference A reference number assigned by the platform
File name The name of the file submitted by the merchant
Upload date The date of the file upload
Status/Progress Displays “Processed” and a fraction representing the number of lines processed over the total number of lines in the Alias files.
Action Blank when the file is processed

File Summary

Item Description
Total operation The total number of lines in the Alias file
Incorrect operations The number of invalid lines that were not processed
Correct operations The number of valid lines that were not processed
Uploaded by The person who uploaded the Alias file
NCMODE The submission mode: Automatic File Upload (AFU) or Manual File Upload (MFU)
Upload date Timestamp of the file upload

Error Description

(Displays only when the file is partially valid or invalid)

Item Description
Error description The description of the error
Error lines The location of the error in the Alias file

3 Other Files

3.1 Upload file

To upload "Other files":

  1. Click “Upload new batch file"
  2. Click "Other files" and "Select File" to select the file you want to upload from your computer
Note:
• If you select to upload a file that is already in the list of processed files, a message pops up to inform you of the existing uploaded file and asks if you would like to continue. Click "Yes" to continue with the upload, or "No" to cancel the file upload.

3.2 Format check

After you have selected the file, you will be directed to the "Transaction File Upload" page (Step 2: Format check) where the file is being checked.

In the format check page, you will see:

  • The first valid transaction in the file (The number depends on the number you have entered in the previous screen)
  • Transaction format validation errors
  • Total amounts per currency
  • Our file reference
  • A list of files uploaded during the last month, containing the same total amounts and/or same sum/addition of card numbers, to prevent you from sending the same file twice
  • A list of files still in a non-final status.
  • The number of Alias operations (Add, Delete) (optional)
  • The number of Subscription operations (Add, Delete) (optional)

For more information about validation statuses, please refer to Chapter 5: Transaction file validation statuses.

Once the file is checked for its format, you can either click "Cancel" to cancel the file upload and be redirected back to Batch Manager where the file status displays “Cancelled” in the Batch list.

If you click "Back", you will go back to Batch Manager. If you click "Continue", the file begins processing. If you click “Back”, you can see the result of the format check on the Batch Manager page. Click icon for more information.

Header Row

Item Description
Reference A reference number assigned by the platform
File name The name of the file submitted by the merchant
Upload date The date of the file upload
Status/Progress The status of the format check.
Action The action you can perform based on the statuses

File Summary

Item Description
Total operation The total number of lines in the Alias file
Transaction code The number of lines that are invalid and will not be processed
Correct operations The number of lines that are valid and that can be processed
Uploaded by The person who uploaded the Alias file
NCMODE The submission mode: Automatic File Upload (AFU) or Manual File Upload (MFU)
Upload date Timestamp of the file upload

When you encounter validation errors, you can respond in two possible ways:

  • You can generate and submit a new file afterwards, containing these ‘red’ transactions, ensuring you have resolved the listed issue for each transaction.
  • You can click the “Cancel” button to cancel the file. You are then able to resolve the errors in the transactions and resubmit the file. If you resolve all the issues, the format check will then be successful and you can continue the processing.

3.3 Process file

After the format check is done, click "Continue" to begin the file processing. An email is sent to notify you of the result when the files are successfully processed.

Click “Continue” after the files are processed. You will be redirected back to the Batch Manager to view the result of the processing.

Details

For a detailed view of the processed transactions, click “Details” and you are redirected to the “Financial history” page.


More options button

The “…” (More options button) lets you do the following:
  • Download: Download a report on the processed file. Click on the icon and “Download” to download the file.
  • Delete: Delete the Other file.

To learn more about the result of the processed file, click the icon and an expanded list and table displays. The following describes the parts of this expanded list and table:

Header Row

Item Description
Reference A reference number assigned by the platform
File name The name of the file that is processed
Upload date The date of the file upload
Status/Progress Displays “Processed” when the file is processed
Action
  • Details: Directs to “Financial history” page
  • … (More options): Download report of the processed file. Delete the invalid file.
  • (Expand icon): Displays a summary of the processed file.

File Summary

Item Description
Total operation The number of total operations processed
Transaction code The code of the transactions done
Amount The amount (in a specific currency) that is processed
Uploaded by The person who uploaded the Alias file
NCMODE The submission mode: Automatic File Upload (AFU) or Manual File Upload (MFU)
Upload date Timestamp of the file upload

Status Details

(Extracted from “Financial history” page)

Item Description
Status Status of the transaction
Card type The card used in the transaction
Number of transactions Number of transactions performed with that card type
Amount The total amount from the transactions performed with the type of currency

Error description

Item Description
Error description Describes the error
Pay ID Details the location of the error via the PAY ID in the file

Operation Details

A list of operation code names and the number of line with the operation(s).

4 File download

You can manually download a payment file (transaction results) by taking the following steps:

  1. Click the “Electronic Reporting” link in your back-office menu.
  2. Select your preferred file structure and file format.
  3. Enter the search criteria for the transaction results you want to download via the “View transactions” or “Financial History” link in your back-office menu or select the transaction file you want to download via the “View files” link in your back office.
  4. Click the "Download List" button.

You can also download your payment files automatically (through an application) instead of manually via the back office. For more information, go to Advanced Batch.

4.1 Electronic reporting

In the Electronic reporting page, you can specify the format and structure you want to use for electronic reports such as file downloads. When push-reports are activated in your account, the electronic reporting link will provide access to a list of your push-reports.

Specific fields will be returned in your file download, depending on the file structure.

A choice of different file structures is available:

  • Standard
  • Extended
  • File Management
  • Dynamic

You can also choose between different return formats:

  • XML
  • Fixed-Length
  • Delimited

For the full description of the download structures, go to the "Description of the downloaded payment files" page in the Support section of your Ingenico ePayments account. You can also find more information on the various file formats in the Advanced Batch documentation.

Tips:

  • To receive an MS Excel result file, we recommend that you use the “Dynamic” structure, “Delimited” (;) file format with .csv extension.
  • For column headers in your result file, please tick the “With Column Headers” checkbox in the “Others” section of the Electronic reporting page.

5 File validation statuses

Other files

Status

Description

Uploaded The file is received, but is not yet validated
To be checked
The file is pending for validation
Checked The file is validated
Cancelled The file is cancelled after the ‘Check’ step
To be loaded The file is waiting to be loaded into our process module (only in ASYNC mode)
Being loaded The file is loaded into our process module
Loaded The file is loaded into our process module, but at least one of the payments have not yet been sent to the acquirers/banks
Processed
All the payments in the file are sent to the acquirers/banks

Alias files

Status

Description

Uploaded The transaction file is uploaded and waiting to be processed
Valid All lines in the transaction file are valid and should be processed within the 60-minute timeframe
Partially valid At least one line in the transaction file is valid and invalid. The transaction file should be processed within the 60-minute timeframe.
Invalid All lines in the transaction file are invalid
Expired The 60-minute timeframe to process the transaction has expired.
Processing The transaction file is being processed
Processed
The transaction file has been processed