Dernière mise à jour 29/10/2014

2. File format: Upload

The following section contains the standard transaction file formatting rules. If you are using another specific format compatible with our system, go to Other file formats.

2.1 General

A payment file should be formatted in compliance with the following few basic rules:

  • The file should be an ASCII text file
  • One line per order. The lines are separated by the Carriage Return and Line Feed characters (ASCII : 13 10 – HEX : 0xD 0xA)
  • The fields must be separated by a semicolon (“;”)
  • The fields themselves cannot contain any semicolons (“;”)

For new transactions (ATR), we automatically split files that are larger than 2750 lines/transactions. If this is not yet the case for your account, please ask notre service clientèle to enable this functionality for you.

For maintenance transactions (MTR), we don't split files, so the amount of lines should be limited to 30 000. However, to ensure that your files get processed swiftly, we recommend you limit each file to 2,500 lines.

2.2 File fields

2.2.1 Layout

A standard batch file has the following transaction layout:

Field no.
Field Description
1
AMOUNT
Amount to be paid MULTIPLIED BY 100 since the format of the amount must not contain any decimals or other separators.
2
CURRENCY
ISO alpha order currency code, for example: EUR, USD, GBP, CHF, etc.
3
BRAND
Card brand (See Appendix 3 for non-credit card payment methods).
4
CARDNO
Card/account number.
5
ED
Expiry date (MM/YY or MMYY).
6
ORDERID
Your unique order number (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, "Default operation code" section of the Technical Information page will define your default transaction operation. When you send an operation value in the Operation field in your batch, this will overwrite the default value.

Possible values for new orders:

  • RES: request for authorisation
  • SAL: request for direct sale (payment)
  • RFD: refund, not linked to a previous payment, i.e. not a maintenance operation on an existing transaction (you cannot use this operation without specific permission from your acquirer).

Optional:

  • PAU: Request for pre-authorisation
      In agreement with your acquirer you can use this operation code to temporarily reserve funds on a customer's card. This is a common practice in the travel and rental industry.
      PAU/pre-authorisation can currently only be used on MasterCard transactions and is supported by selected acquirers. This operation code cannot be set as the default in your Ingenico ePayments account.
      Should you use PAU on transactions via acquirers or with card brands that don't support pre-authorisation, these transactions will not be blocked but processed as normal (RES) authorisations.

Please note that refunds submitted via Batch are not processed until the following day (after the acquirer cut-off time set in your account).

See here for the possible values for maintenance operations.
11
AUTHORIZATION
CODE
Authorisation code, not received via our system.
12 AUTHORIZATION
MODE
The way in which 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 request a maintenance operation on all these transactions at a later time.
...
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 (Card Verification Value).
...
Blank fields

35 ECI

Electronic Commerce Indicator. You can configure a default ECI value in the "Global transaction parameters" tab, "Default ECI value" section of the Technical Information page. When you send an ECI value in the ECI field in your batch, this will overwrite the default ECI value.

0 - Swiped

1 - Manually keyed (MOTO, card not present)

2 - Recurring payments, originating from MOTO

3 - Installment 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 #

Field

 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
55 Blank field ...
56  COF_RECURRING_EXPIRY* currently available in TEST only
End date : date of the last scheduled payment of a series
Values: 

YYYYMMDD (i.e. 20190914)
57 COF_RECURRING_FREQUENCY* currently available in TEST only
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.

Additional fields may also be optionally sent by merchants who have activated certain options/functionalities in their accounts. Please refer to the respective option documentation for more information on additional fields linked to the option.

2.2.2 Minimum required fields for new transactions

This section only applies to new transactions. Go to Maintenance operations for more information on maintenance operations on existing transactions.

General: new transaction

For new transactions that you would like to enter into our system, the minimum fields required at the transaction level are:

  • Amount (field 1 in the file layout)
  • Currency (field 2)
  • Card (or account) number (field 4)
  • Expiry date (field 5)
  • CVC (field 27) (this field is required depending on your acquirer and the ECI value for your transactions)
  • Your order reference (field 6)
  • Operation (field 10)

Example

General: new transaction

10000;EUR;;4111111111111111;11/12;Order0001;;Paul Smith;;SAL;;;;;;;;;;;;;;;;;123;

9500;EUR;;5399999999999999;11/10;Order0002;;Jane Doe;;SAL;;;;;;;;;;;;;;;;;485;

2050;EUR;;4444333322221111;11/09;Order0003;;John Doe;;SAL;;;;;;;;;;;;;;;;;875; 


Exception: authorisations received via an alternative channel

When a (related) transaction does not yet exist in our system, the minimum fields required at the transaction level for authorisations received via an alternative channel (e.g. an authorisation received by phone with your acquirer) are:

  • Amount (field 1 in the file layout).
  • Currency (field 2).
  • Card (or account) number (field 4).
  • Expiry date (field 5).
  • Your order reference (field 6).
  • Card (account) holder name (field 8).
  • Operation (field 10).
  • Authorisation code (field 11).
  • Authorisation mode (field 12).
  • Authorisation date (field 13).

Example

Exception: authorisation already received through an alternative channel

1000;EUR;;4111111111111111;11/12;Order0001;;Paul Smith;;IMP;43785;TEL;08/08/07 15:15:52;

9500;EUR;;5399999999999999;11/10;Order0002;;Jane Doe;;IMP;83145;TEL;08/08/07 15:21:45;

2050;EUR;;4111111111111111;11/09;Order0003;;John Doe;;IMP;73586;TEL;08/08/07 15:26:12;

2.2.3 Magstripe/swipe transactions

For transactions accepted inflight through magnetic stripe/swipe, "TRACK2" data can be sent in line 42 of a batch file.

TRACK2 is a track read by ATMs and credit card checkers. It contains the cardholder's account, encrypted PIN, and other discretionary information. 

2.3 Headers and Footer

You will need to use the headers and the footer if you are uploading your files automatically or sending maintenance operations in your file.

There are two headers: OHL containing login information and OHF containing general file information. The headers have to be entered in the first lines of the file, before the actual payment data.

There is one general file footer called OTF. The file footer has to be entered as the last line of the file, after the actual payment data. The footer layout is simply “OTF;”.

The following example shows a file containing both headers and footer. In the following sections, we will take a closer look at the layout of the login information and file information headers.

Example

OHL;FishShop1;MySecret84;;FishAPI;

OHF;File53484;ATR;RES;2;

10000;EUR;;4111111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;;123;

9500;EUR;;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;;485;

OTF;

2.3.1 OHL: Login information header

Only use a Login Header when you are uploading your files automatically (exception: manual file upload on a Group).

Login Header layout:

OHL;PSPID;PSWD;USERTYPE;USERID;

Field
Description
OHL
Fixed value, indicating this is a header containing login information
PSPID
Your affiliation name in our system
PSWD
The password belonging to your user (> USERID)
USERTYPE
Only applicable for Group structures, value: MGID
USERID
Your (API) user (please refer to the User Manager documentation for more information on API users)

The fields you fill in will depend on whether you use the login details from:

  • Your PSPID and a USERID
  • A Group: when you have a “Group” structure and you want to send a file containing transactions for more than one PSPID belonging to your group, the login details need to contain a (default) PSPID that belongs to your group and a “Group” level user (as opposed to a user belonging to a specific PSPID).

We will illustrate this in the following examples:

Examples

Merchant login header

Mike has a PSPID called MilkyMike. He wants to submit his files automatically from an application at his end. To do this, he has created an API user called MikeAPI in his account, with A78H29U41 for the password. His login header would be:

OHL;MilkyMike;A78H29U41;;MikeAPI;

Group login header

John Doe Trading has 3 different PSPIDs: JohnUK, JohnUS and JohnAU. They have a group structure, called JohnDGroup, grouping the 3 PSPIDs together. In JohnDGroup, they have created an API user called JohnUser1 with MySecret12 for the password.

John wants to automatically submit a file containing transactions for the 3 different PSPIDs. He has the most transactions in the UK. This is what his login header will look like:

OHL;JohnUK;MySecret12;MGID;JohnUser1; 

2.3.2 OHF: File information header

File Header layout:

OHF;FILE_REFERENCE;TRANSACTION_CODE;OPERATION;NB_PAYMENTS;

Field
Description
OHF
Fixed value, indicating this is a header containing general file information
FILE_REFERENCE
Mandatory reference (name) for the file, freely definable. You can use this reference to look up your file afterwards. (max. 50 characters)
TRANSACTION_CODE

Possible values:

  • ATR: code for new orders (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.
OPERATION

For new orders: left blank, RES, SAL, RFD

For maintenance operations: REN, DEL, DES, SAL, SAS, RFD, RFS

(Go to File fields and File specifics for operation explanations)

The OPERATION parameter at the file level can be overwritten by the OPERATION parameter at transaction level.

NB_PAYMENTS
Number of payments in the file. Numeric. Mandatory unless you are using a file footer (in which case we still suggest you use this field).

Example

File information header for new orders

Jane has a file called Membership0607 containing 86 requests for authorisation. Her file information header would be:

OHF;Membership0607;ATR;RES;86;

File information header for maintenance transactions

Mike has a file called RefundsJune containing 9 (final) refunds. His file information header would be:

OHF;RefundsJune;MTR;RFS;9; 

The login and file information details can be transmitted in file headers, as illustrated above, or as parameters in HTTP POST requests (only for automatic file upload).

Ingenico ePayments est la division de commerce mobile et en ligne du groupe Ingenico. Nous connectons les commerçants avec les consommateurs, permettant à toutes les entreprises, où qu’elles soient, de franchir les frontières existantes, et créant ainsi l’avenir du commerce mondial. En tant que leader du secteur depuis 1994, notre esprit d’innovation nous propulse en avant sur l’ensemble des canaux de vente. Nous sommes le partenaire de confiance de plus de 65 000 commerçants de toutes tailles qui comptent sur nous pour faciliter et sécuriser les paiements de leurs clients. Grâce à notre système avancé d’analyse de données, nos solutions de gestion des fraudes et notre expertise commerciale internationale, nous aidons les commerçants à optimiser leurs activités et à se développer sur de nouveaux marchés dans le monde entier.

Ce site utilise les cookies pour être capable de vous donner la meilleure expérience utilisateur. Si vous ne souhaitez pas accepter ces cookies, nous vous permettons de modifier les paramètres des cookies. Cliquez sur «Accepter» pour permettre tous les cookies de ce site.

Paramètres des cookies

Introduction

Fonctionnels

Les cookies fonctionnels assurent le bon fonctionnement du site et ne peuvent pas être désactivés.

Optimisés

Les cookies d'optimisation nous permettent d'analyser l'utilisation du site afin de l'améliorer.
C'est le niveau par défaut.

Personnalisés

Les cookies de personnalisation, utilisés pour les médias sociaux et la personnalisation avancée, nous permettent d'afficher vos informations en lien avec votre société.


Exemple de fonctionnalité autorisée

  • Mémorisation du pays préféré
  • Mémorisation de la langue préférée

Exemple de fonctionnalité non autorisée

  • Enregistrement des données personnelles des utilisateurs
  • Suivi anonyme via Google Analytics
  • Suivi à des fins de remarketing

Exemple de fonctionnalité autorisée

  • Mémorisation du pays préféré
  • Mémorisation de la langue préférée
  • Suivi anonyme via Google Analytics

Exemple de fonctionnalité non autorisée

  • Enregistrement des données personnelles des utilisateurs
  • Suivi à des fins de remarketing

Exemple de fonctionnalité autorisée

  • Mémorisation du pays préféré
  • Mémorisation de la langue préférée
  • Suivi anonyme via Google Analytics
  • Affichage de contenus en fonction de vos intérêts
  • Affichage de publicités en fonction de vos intérêts
  • Suivi à des fins de remarketing

Exemple de fonctionnalité non autorisée

  • Enregistrement de données personnelles