1 Principles of Batch manager

This Manual describes the 1cs Online Payment System Batch Manager, which can submit collected transactions in batch files.

The following section Introduction offers a short introduction on how Batch Manager can be used. It the section Name of the batch files it describes how batch files must be named. The exchange of batch files with the 1cs Online Payment System is described in section Manual transfer of batch files as well as FTP-transfer of batch files.

Batch files must be correctly structured to enable the 1cs Online Payment System to process them. Section Format of batch files describes how the transaction data in the batch file must look.

1.1 Introduction

Batch Manager lets you transmit payment transactions in the form of files. In this process you assemble transaction data such as the credit card number, amount and currency in a batch file which is transmitted to the 1cs Online Payment System. the 1cs Online Payment System then makes the authorization or payment and saves the transaction status in the batch file. After processing, the merchant can access the batch file with the details on the transaction status via download.

1.2 Name of the batch files

The name of a new batch file begins with the letter T to indicate the file was originally transmitted by you. This is followed by the Date of the submission in reverse order: e.g. 20160112. This is followed by the MerchantID issued by First Cash Solution and a three-figure Counter, which starts at 001. If you submit several files on one day, you need to set the counter to 002, 003, 004 etc. The file must end in .DAT.

Notice: Please note that the order of the components depends on whether you as the merchant transmit the batch files manually via the Merchant Cockpit or automated by FTP or sFTP. For an example of the FTP/sFTP transmission, see Chapter FTP-transfer of batch files.

The name of a batch file comprises four components:

File name for manual transmission via the Merchant Cockpit and for automated FTP transmission:

<Phase><Date><MerchantID><Counter>.dat

Please pay attention that file name is different for the Merchant Cockpit and SFTP-transmission.

Component	Description
Phase	T=Transferring, P=Processed
Date	Date in format YYYYMMDD (Year, Month, Day)
Counter	Three digit, counts up daily from 001, 002 to 999
MerchantID	MerchantID

The processing of the batch file goes through several phases which are indicated within the file name: The original file form the merchant starts with the character T. After processing, the batch file is suffixed with the letter P for Processed.

If a merchant with the MerchantID TestHandler submits two batch files on 12/01/2016 via the Merchant Cockpit, these two files are named as follows:

T20160112001MerchantID.dat
T20160112002MerchantID.dat

Notice: After you have transmitted the batch file the processing of the transactions begins. After the transmission and during the processing the file is prefixed W for Waiting. If the T batch file is submitted via FTP/sFTP for processing, the phase must be renamed W after the upload by the merchant system. The processing only starts after this step.

W20160112001MerchantID.dat
W20160112002MerchantID.dat

Once all payment transactions have been carried out, the 1cs Online Payment System marks the processed files, which now contain the details of the transaction status, with the initial­ letter P for processed, which You can access in the batch view of the Merchant Cockpit via download:

P20160112001MerchantID.dat
P20160112002MerchantID.dat

1.3 Manual transfer of batch files

The batch interface is integrated into the Merchant Cockpit, which you can also use for the administration of your transactions. In order to transmit a batch file, first log in to your account from the Merchant Cockpit using your Internet browser. Note that batch handling must be activated for working with batch files. Select the Create transactions menu option in the Merchant Cockpit and click on the Batch files tab. From there you can find and list up submitted and processed batch files using the search and filter function. In the Transaction features combobox, select the File for processing status in order to list up all batch files currently being processed. A search for the Processed file transaction feature, conversely, shows you the batch files that have already been completely processed, in each case with the status of the payments. Clicking on the file name lets you download and save the batch files onto your PC.

To transmit a new batch file to the the 1cs Online Payment System, click on the Upload button and then select the file from the local hard drive of your computer with the Browse button. You can now start the transmission with the Upload button.

The batch view of the 1cs OBS

Notice: The processing of the transmitted batch file starts shortly after the transmission. Since all batch files are processed in turn, the processing of your transmitted batch file does not begin until previously transmitted batch files have been processed.

After the transmission and during the processing the file is prefixed W for Waiting. When all payments in the batch file all have been processed, the batch file is allocated the new initial P. You can click on these processed files in the the Merchant Cockpit batch view, download them to save on your computer, analyse them with Excel or forward them to Accounts.

1.4 FTP-transfer of batch files

In addition to manual batch transfer (see also Manual transfer of batch files) the 1cs Online Payment System also lets you transfer batch files automatically via FTP (File Transfer Protocol). To transfer a batch file via FTP/sFTP, proceed as follows:

1.     Save the transaction data in a formatted batch file

2.     Encryption of the batch file

3.     Transfer the batch file

4.     Change of the phase after the upload (T ® W)

5.     Retrieve the batch file after processing

6.     Check status of transactions

Save transactions in the batch file

The transaction data in the batch files must correspond to the structure described in the following section Format of batch files.

Encryption of the batch file

For reasons of security, batch files must be encrypted before the FTP/sFTP transmission. To guarantee maximum security the the 1cs Online Payment System uses asymmetric encryption with PGP (Pretty Good Privacy). Encryption with GPG (GNU Privacy Guard) is also possible. The saved file must, however, have the extension .PGP, otherwise no processing is possible.

If several batch files are to be submitted, for example for a Merchant with the MerchantID MerchantID on the 12/01/2016, then these two files are named as follows (see also Name of the batch files):

T20160112001MerchantID.dat
T20160112002MerchantID.dat

The recognised high security of PGP-encryption is based on a process with two keys, a private key and a public key. First Cash Solution provides you with a public key for encryption of your batch file. The encrypted batch file can then be decrypted only with First Cash Solution’s secret private key.

You can also generate public and a private key for your company. the 1cs Online Payment System encrypts the processed batch file with your public key. The file can then be read only with your secret private key.

2 Format of batch files

The content of a batch file consists of a header, several records and a footer. Each entry in the file is one row which is completed with CRLF (Enter key). The values within a line are comma-separated. The format is thus also described as the CSV format (Comma Separated Values).

The following sections describe the format of the batch file which you transmit to the 1cs Online Payment System and the response-file, in which the 1cs Online Payment System saves the results of the payments.

2.1 Format of batch files submitted

The listing below shows the components which make up the content of a batch file.

Notice: Please note that the batch file may not include any empty rows either at the start or the end of the file. The empty rows in the listings are for ease of reading only.

Notice: Please note that text parameters like “Reason” or “OrderDesc” may not contain commas.

Notice: In Batch versions 2.x there is another field for <MID>. Thereby it is possible for a MasterMID to submit transactions for SubMID.

Header

Type,MerchantID,Date,Version

Record

Type,Action,<Amount>,<Currency>,<TransID>,<Data depends on Action>

Footer

Type,CountRecords,SumAmount

The following listing is an example of a batch file for the capture of three credit card transactions to the value of 1.00 and 2.00 euro’s. For the first payment the merchant system supplies the reference number 123456 but no reference numbers are supplied for the second and third:

HEAD,MerchantID,20160112,1.2

CC,Sale,100,EUR,1567890,123456,MasterCard,5490011234567890,200506,Your order from Jan. 4.

CC,Sale,100,EUR,1567891,,MasterCard,5490011234567890,200506,Your order from Jan. 4.

CC,Sale,200,EUR,10202280,,VISA,4907621234567890,200504,Your order from Jan. 4.

FOOT,3,400

The description of the individual fields and values used within the data set (Record) within the batch file you will find in the respective chapter within the manual of the individual payment method.

The general parameters for transfer within Header and Footer explains the following table:

Parameter	Format	CND	Description
Type	a..11	M	HEAD for Header, FOOT for Footer, and for example CC for credit card. The field need not contain 11 digits.
MerchantID	ans..30	M	MerchantID, assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too.
Date	dttm8	M	Date of file-production in format YYYYMMDD
Version	an6	M	The used batch version determines which optional parameters are used additionally. The possible batch versions in each case differ depending on the payment method and executed action. You will find the possible versions within the batch chapter of the respective payment method.
CountRecords	n..5	M	Number of submitted Records without Header or Footer
SumAmount	n..12	M	Total of all Amounts in smallest currency unit, e.g. cents in the case of euro’s in accordance with currency table. Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Description of general parameters in the header and footer of batch files

2.2 Format of batch response files

During the processing of the transactions the Batch Manager saves the transaction status to the batch file. To this end two fields, Status and Code, are added to the transaction entries in the Record area:

Record

CC,Capture,<Amount>,<Currency>,<TransID>,<RefNr>,<PayID>,<Status>,<Code>

Notice: If using the authorisation renewal the Batch-response file can include more rows than you have submitted because the the 1cs Online Payment System reports failed authorisation renewals as Renewal or AuthSplit with the status FAILED. In this case you need to contact the customer!

Notice: The return of optional parameters in the response file generally occurs only if these were included in the submitted file. Generally no shipment information are given in the response file. If you need this data again, please read this data from the corresponding Notify.

The particular response parameters which Batch manager stores in the record section for each transaction you will find in the batch chapter for the respective payment method.

2.3 Batch error codes

From Version 3.0 the 1cs Online Payment System supports detailed error codes. These are eight-digit, hexadecimal codes. The structure and the meaning of the Error codes are described here on the basis of the following example:

2 105 0014

The first digit describes the degree of severity of the error. All values greater than 0 indicate warnings or errors.

Notice: An error code doesn’t necessary mean that the the 1cs Online Payment System or the merchant system has suffered a technical error. the 1cs Online Payment System also generates an error code if a transaction has failed because the bank regular refuses a payment.

The 2nd to 4th digits of the error code describe the error category. The error categories relate to encryption (001) and format errors (010) and the details of payment methods, initiated in the case of credit cards (100) through direct debits (110) to Cash&Go (140).

The 5th to 8th digits of the error code give an indication of the error details. Details include instructions on configuration problems such as missing TerminalIDs (0047) and failures at the card holder’s bank computing centre (121) but also standard refusals of credit card payments based on expired cards (110) or declined messages (0100).

Notice: Error-free transactions, for reasons compatibility with Version 2.1, are not characterised by eight but by a zero 0.

You can find a full list of the 1cs Online Payment System Error codes in the Excel-file of Error codes in the respectively current the 1cs Online Payment System Client which you can download from our Homepage.