Appendix 2 - Input file specifications

This chapter describes the structure of the Standard PagoPA file, i.e. the transaction file to be used as an input for the batch service elaboration, the output file produced by the batch service will have the same format.

The naming convention of the file is as follows:

• [service].[ABI].[filetype].[date].[time].[nnn].csv

in particular:

field	format	notes
service	Alphanumeric - 5 char	fixed value "CSTAR"
ABI	Alphanumeric - 5 char	sender ABI code or PagoPA 5 char assigned code (if ABI not available)
filetype	Alphanumeric - 6 char	Fixed value "TRNLOG"
[date].[time]	YYYYMMDD.HHMISS	file creation timestamp
nnn	Alphanumeric - 3 char	Progressive value of the file (e.g. 001)

Please note that:

• The file is in .csv format, with separators “;”

• The contents of the file do not include head and tail records but only detail records, according to the layout below.

• Please note that the input file must not be empty otherwise it remains in the Input directory

• Each file submitted must have a unique name compared to all the previous ones.

Fields in the Standard PagoPA file

field	Type	Mandatory	Notes
sender_code	Alphanumeric - max 5 char	YES	ABI code of the sender. If not available, a 5 char code assigned by PagoPA
operation_type	Numeric - regexp [0-9]{2}	YES	Operation type: 00 - payment 01 - reversal of payment xx - future uses
circuit_type	Alphanumeric - regexp [0-9]{2}	YES	Payment circuit: 00 – Pagobancomat 01- Visa 02- Mastercard 03- Amex 04- JCB 05- UnionPay 06- Diners 07- PostePay Code 08- BancomatPay 09- SatisPay 10- private circuit (onus, onwe) 12 - AliPay 13 - WeChat 14 - TPay 15 - Monni 16 - Discover 99 - other (to use in case previous codes do not apply)
pan/hpan	Alphanumeric max 64 char	YES	PAN of the payment instrument used. In the case of a non-card based circuit, will be the unique identifier of the payment instrument, the same the user can register using the IO App or a touch point from the Issuer bank. In the input file the information must be provided unencrypted, in the output file the information will be hashed
date_time	ISO8601 date. It must be compliant with the following DateTimeFormatter pattern: yyyy-MM-dd'T'HH:mm:ss.SSS[XX][XXX]	YES	Timestamp of the payment transaction carried out with the Merchant. Please note that the second details are not always available for all transactions. In this case, the field will be padded with all '0's
id_trx_acquirer	Alphanumeric -max 255 char	YES	Unique identifier of the transaction at the Acquirer level. - can be populated with the ARN, or if this data is not present, with a unique id that allows to uniquely identify the transaction on the Acquirer side.
id_trx_issuer	Alphanumeric -max 255 char	YES	Authorization code issued by the Issuer (ex: AuthCode). If the record not have the the AuthCode (es:. reversal operation - operatio_type = 01) insert fixed value MISSING
correlation_id	Alphanumeric -max 255 char	NO	Correlation identifier between payment transaction and possible reversal. The field is mandatory if the record refers to a reversal operation (operation_type = 01)
amount	Numeric	YES	Valued in euro cents (ex: 10€ = 1000) and expressed in absolute value: the sign is assumed from the type of operation “00-payment, 01-reversal"
currency	Alphanumeric - max 3 char	YES	Fixed value 978 = EUR. International ISO coding is used.
acquirer_id	Alphanumeric -max 255 char	YES	The Abi code of the acquirer who authorized the transaction if it's not in the transaction it would be assign to you from PagoPa
merchant_id	Alphanumeric -max 255 char	YES	Unique identifier of the physical store of the Acquirer (also known to the Merchant and used by the same to register on the Automatic Billing platform). - In the Pagobancomat circuit it can correspond to the field: merchant
terminal_id	Alphanumeric -max 255 char	YES	Identification of the Merchant's terminal/POS (Point of Sale). - In the Pagobancomat circuit it corresponds to the field: cashier premises - Visa/Mastercard circuit: terminal_id
bank_identificatio n_number (BIN)	Alphanumeric or - regexp [0- 9]{6}|[0-9]{8}	YES	Code containing the first 8 digits of the payment instrument. - In the Pagobancomat circuit it corresponds to the field: codice_abi
MCC	Alphanumeric -max 5 char	YES	Merchant Category Code.
fiscal_code	Alphanumeric - max 16 char	YES	Fiscal code for legal person and for natural person (self-employed workers).
VAT	Alphanumeric regexp [0-9]{11}	NO	VAT Code, Tax Code legal person. The fied is mandatory if fiscal_code record refers to a legal person
pos_type	Alphanumeric regexp [0-9]{2}	YES	POS Type: 00 - physical POS 01 - e-commerce
PAR	Alphanumeric	NO	Payment Account reference The field must contain the information of the PAR, which can be defined as a collector capable to associate each TokenPAN with the PAN of the physical card, thanks to the unique and immutable association between PAN and PAR and Token and PAR