Principles of Batch manager

This Manual describes Pay-Jet Cockpit 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 Pay-Jet Cockpit 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 Pay-Jet Cockpit to process them. Section Format of batch files describes how the transaction data in the batch file must look.

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 Pay-Jet Cockpit. Cockpit 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.

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 a three-figure Counter, which starts at 001 and the MerchantID issued by Pay-Jet. 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.

The name of a batch file comprises four components.

File name for manual transmission via Pay-Jet Backoffice:

File name for automated FTP transmission:

Please pay attention that file name is different for Pay-Jet Backoffice and SFTP-transmission.

Components of batch file names

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 MerchantID submits two batch files on 12/01/2016 via Pay-Jet Backoffice, these two files are named as follows:

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.

Once all payment transactions have been carried out, Cockpit 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 Pay-Jet Backoffice via download:

Encoding for batch files

The encoding is relevant if special characters are to be used, e.g. é or similar. In batch files such special characters can be present in the parameter OrderDesc or text fields.

In general, UTF-8 as encoding is a good choice for the delivery of batch files. UTF-8 BOM (with ByteOrderMark) is also supported.

Manual transfer of batch files

The batch interface is integrated into Pay-Jet Backoffice, 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 Pay-Jet Backoffice using your Internet browser. Note that batch handling must be activated for working with batch files. Select the Create transactions menu option in Pay-Jet Backoffice 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 Pay-Jet Cockpit, 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 Pay-Jet Backoffice

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 Pay-Jet Backoffice batch view, Download them to save on your computer, analyse them with Excel or forward them to Accounts.

FTP-transfer of batch files

In addition to manual batch transfer (see also Manual transfer of batch files) Pay-Jet Cockpit 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 Cockpit 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):

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

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

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 Cockpit and the response-file, in which Cockpit saves the results of the payments.

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:

Description of general parameters for Header and Footer of batch files

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

Batch error codes

From Version 3.0 Cockpit 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:

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 Cockpit or the merchant system has suffered a technical error. Cockpit 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 Cockpit response codes here. Our latest Cockpit Client can be downloaded here.