1. Home
2. Integration Solutions
3. Integrations
4. Viveum Batch (Basic)

1. Introduction

The Viveum 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.

The graph above shows a transaction flow with Batch integration

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

2. File selection

From your Viveum account, click Operations > New file. 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 (# / Name)	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 Viveum 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 (# /  Name)	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
Blank field	...
56 / COF_RECURRING_EXPIRY*	End date : date of the last scheduled payment of a series Values: YYYYMMDD (i.e. 20190914)
57 / COF_RECURRING_FREQUENCY*	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 Viveum 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;Visa;4111111111111111;11/02;Order0001;;Paul Smith;
100;EUR;Visa;4111111111111111;11/02;Order0002;; Bill Durand;
2032;EUR;Visa;4111111111111111;11/02;Order0003;;John Doe;
OTF;

(or)

1000;EUR;Visa;4111111111111111;11/02;Order0001;;Paul Smith;
100;EUR;Visa;4111111111111111;11/02;Order0002;; Bill Durand;
2032;EUR;Visa;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 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.

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 Viveum 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