Last update 2/06/2014

1. Introduction

The Ingenico ePayments Batch mode enables you to group your payments into formatted uploadable files. This option is particularly suited for large numbers of payments or recurrent invoicing. In this guide, you will learn to upload and manage Alias and Other files in Batch Manager.

For more advanced information about Batch (e.g. automating the upload and download process), go to Advanced Batch.

2. 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 #
Field
Description
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


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;

3. Alias Files

3.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. 

3.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).

3.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

4. Other Files

4.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.

4.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 6: 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.

4.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).

5. 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.

5.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.

6. 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 

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data