About Batch files
Batch Manager allows you to transmit payment transactions as files. This file transfer can be done:
- Manually via the Axepta back-office (Please refer to the Back-office document)
- Automatically via the secure file transfer protocol (sFTP)
In this process you assemble transaction data such as the transaction ID, amount and currency in a batch file that you will later transmit to the payment platform. The payment platform then makes the payments and saves the transaction status in the batch file. After processing, the merchant can access to the batch file with the details on the transaction status via a download.
SFTP access for Batch file transfer must be requested at the BNP Paribas Helpdesk.
Batch files must be correctly structured to enable the payment platform to process them.
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 BNP. 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 Axepta Backoffice:
<Phase><Date><MerchantID><Counter>.dat |
File name for automated FTP transmission:
<Phase><Date><Counter><MerchantID>.dat |
Please pay attention that file name is different for Axepta Backoffice and SFTP-transmission.
Component | Description |
|---|---|
Phase | T=Transferring, P=Processed |
Date | Date in format YYYYMMDD (Year, Month, Day) |
Counter | Three digits, 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 sent by the merchant starts with the character T (for Transferred). 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 Axepta Back Office, these two files are named as follows:
T20160112001MerchantID.dat |
Notice: After you have transmitted the batch file, the processing of the transactions begins. During this processing the file is prefixed with 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 payment platform 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 BNP Paribas Back Office via download.
P20160112001MerchantID.dat P20160112002MerchantID.dat |
FTP transfer of Batch files
The payment platform allows you to transfer batch files automatically via FTP (File Transfer Protocol). To transfer a batch file via FTP/sFTP, proceed as follows:
- Save the transaction data in a formatted batch file
- Encrypt the batch file
- Transfer the batch file
- Change of the phase after the upload (T → W)
- Retrieve the batch file after processing
- Check status of transactions
Encryption of the Batch file
For security reasons, batch files must be encrypted before the FTP/sFTP transmission. To guarantee maximum security the payment platform 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 |
The recognized high security of PGP-encryption is based on a process with two keys, a private key and a public key. BNP Paribas provides you with a public key for encryption of your batch file. The encrypted batch file can then be decrypted only with BNP Paribas's secret private key.
You can also generate public and a private key for your company. The payment platform 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 the payment platform and the response-file, in which the payment platform saves the results of the payments.
Format of submitted Batch files
Introduction
The example 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> |
The data to be used depend on Batch version and Action. For more details, please see section "Batch calls and answers" below.
Footer
Type,CountRecords,SumAmount |
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.
Header and Footer
The general parameters for transfer within Header and Footer explain the following table:
Parameter | Format | CND | Description |
|---|---|---|---|
Type | a..11 | M | HEAD for Header, FOOT for Footer, and for example CC for card. The field need not contain 11 digits. |
MerchantID | ans..30 | M | Merchant ID provided by BNP Paribas |
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). |
Record
This section describes the parameters which must be transferred within the data set (Record) for executing a credit card payment and which information can be found within the response file about the payment status.
Notice: Within Batch process not all functions of online interface are available.
For Batch calls there must be considered batch versions, from which optional parameters depend. All version designations starting with „2.“ pertain calls for a group of enterprises. That means within a batch file for a particular MerchantID can be transferred transactions for other merchants with a separate Sub-MID.
Operations
Following table gives an overview of all batch versions that are possible for a specific action and their specialities:
Authorize | 1.2 / 2.2 | with textfeld1, textfeld2, RTF, cardholder, transactionID, schemeReferenceID |
| 1.21 / 2.21 | with textfeld1, textfeld2, RTF, approvalcode, cardholder, transactionID, schemeReferenceID |
| 1.3 / 2.3 | with CVC, transactionID, schemeReferenceID |
| 1.5 / 2.5 | with CVC, Zone |
Capture | 1.2 / 2.2 | with textfeld1, textfeld2 |
| 1.21 / 2.21 | with textfeld1, textfeld2, approvalcode |
| 1.4 / 2.4 | with stop of authorisation renewal (FinishAuth) |
CaptureEx | 1.3 / 2.3 | with CVC |
Credit | 1.2 / 2.2 | with textfeld1, textfeld2 |
| 1.21 / 2.21 | with textfeld1, textfeld2 |
| 1.4 / 2.4 | with stop of authorisation renewal (FinishAuth) |
CreditEx | 1.2 / 2.2 | with textfeld1, textfeld2 |
| 1.21 / 2.21 | with textfeld1, textfeld2 |
| 1.3 / 2.3 | with textfeld1, textfeld2 |
Sale | 1.2 / 2.2 | with textfeld1, textfeld2, RTF, cardholder, transactionID, schemeReferenceID |
| 1.21 / 2.21 | with textfeld1, textfeld2, RTF, approvalcode, cardholder, transactionID, schemeReferenceID |
| 1.3 / 2.3 | with CVC, textfeld1, textfeld2, transactionID, schemeReferenceID |
| 1.5 / 2.5 | with CVC, Zone |
Reverse | 1.x / 2.x | Standard version |
Description of the possible batch versions
The structure for a credit card payment within a Batch file to be submitted is the following:
|
Versions
Example for batch versions:
Version 1.2
|
Version 1.21
|
Version 1.3
|
Version 1.5
|
Examples
Examplefor Master MID function:
|
The following example is a batch file for the capture of three card transactions to the value of 1.00 and 2.00 euros. 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 |
Fields
The following table describes the individual fields and values used within the data set (record) in the batch file:
Parameter | Format | CND | Description |
Type | a..11 | M | HEAD for Header, FOOT for Footer, CC for credit card |
Action | a..20 | M | The parameter Action defines the type of transaction: Authorize (authorisation) Capture Sale Credit CreditEx (credit note without previous capture; please agree this with Axepta Helpdesk beforehand) Reverse (cancellation) |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Axepta Helpdesk, if you want to capture amounts <100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table EN |
| PayID | an32 | M | ID assigned by Platform for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
TransID | ans..64 | M | TransactionID which should be unique for each payment. Please note for some connections the different formats that are given within the specific parameters. |
RefNr | an..12 | M | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional BNP settlement file (CTSF) we cannot add the additional payment data. |
OrderDesc | ans..127 | O | Description of purchased goods, unit prices etc. |
CCBrand | a..22 | C | Credit card brand. Please note the spelling! According to table of credit card brands! |
CCNr | n..16 | C | Credit card number at least 12-digit, numerical without spaces. You can optionally transmit also a pseudo card number (PCN) |
| PCNr | n16 | O | Pseudo Card Number: Random number generated by Platform which represents a genuine credit card number. The pseudo card number (PCN) starts with 0 and the last 3 digits correspond to those of the real card number. You can use the PCN like a genuine card number for authorisation, capture and credits. PCNr is a response value from Platform and is sent as CCNr in Request or part of card-JSON |
| CCExpiry | n6 | OC | Optional in combination with PCNr: Expiry date of the credit card in the format YYYYMM (202207). |
CCCVC | n..4 | O | Card verification number in Version 1.3: In the case of Visa and MasterCard the last 3 numbers on the signature strip of the credit card. 4 numbers in the case of American Express. |
FinishAuth | ans1 | O | Version=1.4: If using the authorisation renewal, cancel repeat with the value Y in the field FinishAuth in the case of Capture or Credit. Example: You capture a partial delivery. The rest of the order cannot be supplied. You therefore enter Y in the FinishAuth field for Part-capture so that the Platform does not authorise the remaining amount. Please note for this also the following section about Cancel authorisation renewals. |
| RTF | a1 | O | Subscription with fxed amount and duration
Subscription with variable amount and duration
|
Description of fields within the record for 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:
Introduction
CC,Capture,<Amount>,<Currency>,<TransID>,<RefNr>,<PayID>,<Status>,<Code> |
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 is 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.
Record
The record area within the response file for Batch transactions looks as follows:
|
Versions
Example for batch versions:
Version 1.2
|
Version 1.21
|
Version 1.3
|
Version 1.5
|
Fields
The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):
Parameter | Format | CND | Description |
Action | a..20 | M | The parameter Action defines the type of transaction like capture or credit – see above. |
| PayID | an32 | M | ID assigned by Platform for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
Status | a..50 | M | OK or FAILED |
| Code | an8 | M | Error code according to Platform Response Codes (A4 Error codes) |
PCNr | n..16 | C | The Pseudo Card Number is only returned in the case of transaction types Authorize or Sale & CreditEx. It starts with 0 and the last 3 digits correspond to those of the real card number. |
Description of result parameters within the record for Batch files
Batch error codes
From Version 3.0, the payment platform 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 payment platform or the merchant system has suffered a technical error. The payment platform 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 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 card payments based on expired cards (110) or declined messages (0100).
Notice: Error-free transactions, for reasons compatibility with Version 2.1, are not characterized by eight but by a zero 0.
You can find a full list of the payment platform’s error codes in a separated excel-file provided to you.