About this Guide

This guide serves as a reference to the format and contents of the reports generated and delivered via the Smart Data product.


Intended Audience

This document is intended for technical personnel who will be retrieving and parsing reports generated by the Smart Data system.


Data Formats

FormatDescription

a

Alphabetic

as

Alphabetic with special characters

n

Numeric

an

Alphanumeric

ans

Alphanumeric with special characters

ns

Numeric with special characters

bool

Boolean Expression (true or false)

3

Fixed length with 3 digits/characters

..3

Variable length with maximum 3 digits/characters

enum

Enumeration of allowed values

dttm

ISODateTime (YYYY-MM-DDThh:mm:ss)


Definitions

Payment/
Transaction

Please note that the terms payment and transaction are used interchangeably throughout this document. A payment respectively a transaction may encompass a number of operational activities.

During a transaction lifecycle, the state of a transaction will change, depending on the performed action. These actions may include authorization, capture, sale, cancel and refund. A transaction is thereby defined as a sequence of actions.

Action

An action is an operation that changes the status of a payment when performed successfully.

Job

In the context of Smart Data a job contains a set of general information about the report layout, filter options and data fields.

Task

A task is the actual representation of a job with an assigned execution time.


Product Overview

Smart Data is an automated service designed to create one or more predefined reports that are made available in a merchant’s FTP account for retrieval. The service enables merchants to schedule periodic reports according to their individual needs.

Smart Data reports are delivered as delimited text files (CSV) with a standard set of data fields by default. Merchants however may customize their reports by choosing the fields from the standard set they would like have included. Data records may encompass transactions between one day and maximum one year prior to the report date. Please note that real-time data are not supported through this product.

For individual setup and configuration please contact .


Report Filter

The following filter options are available:

  • MerchantID
  • Company
  • Currency
  • Payment Method
  • Payment Status
  • Card Brand
  • Action
  • Successful transactions only
  • Unsuccessfull transactions only
  • Only transactions with specific Code/s,
  • Only transactions without specific Code/s

Please note that all filter options may contain multiple values.


Report Schedule

Smart Data reports can be setup according to the following options:

Once-off Report

  • Given time period between two dates

Periodic Reports

  • Daily
  • Weekly (weekday of delivery at merchant’s discretion)
  • Monthly (on 1st, 2nd, 3rd, ... each month)


File Layout

Smart Data reports are created as plain text files in CSV format. Currently comma, tab and colon are supported delimiters to separate values (please contact for individual setup). The default delimiter is colon unless specified otherwise.

Each file will contain an initial header row and zero or more data rows. A header row will consist of a separated list of the individual field names, as defined in this document, in the specified order. The field names of the header row are currently available in English and German. The data rows will consist of a separated list of the data field values that contain characters encoded in UTF-8.


Security

For security reasons all files are PGP encrypted and transferred via SFTP.


File Names

The file names are assigned according to the following convention: SmartData_[JobID]_[TaskID]_[YYYYMMDD_hhmmss].CSV.pgp

The individual name elements are described in the table below.

#

Element

Format

Example

1

Prefix

a17

SmartData

2

JobID

n..10

Internal job identifier

3

TaskID

n..10

Internal task identifier

4

Timestamp

an15

YYYYMMDD_hhmmss

A valid file name example is: SmartData_12_789_20160320_023609.CSV.pgp


Data Records and Field Description

Each record represents an operation/action that has been performed on a payment. Regularly a payment will consist of multiple operation records. Available data fields are listed in the table below. Individual data fields can be omitted on request.

#

Parameter

Format

Description

01

PaymentID

an..32

Payment identifier generated by

02

MerchantID

an..20

Merchant identifier assigned by

03

Payment Date

ans19

Timestamp of payment creation time: DD.MM.YYYY hh:mm:ss

04

TransID

ans..64

Transaction identifier assigned by the merchant on payment level

05

RefNr

ans..30

Supplementary transaction identifier assigned by merchant on payment level

06

Amount Auth

n..10

Authorized amount in its smallest unit of transaction currency

07

Amount Cap

n..10

Captured amount in its smallest unit of transaction currency

08

Amount Cred

n..10

Refunded amount in its smallest unit of transaction currency

09

Currency

a3

ISO 4217 three-letter currency code

10

Payment Status

a..30

Transaction status with one of the following values:

·         AUTHORIZED

·         CANCELED

·         CAPTURE_REQUEST

·         CREDIT_REQUEST

·         FAILED

·         OK

·         PENDING

·         SUCCESS

Please note that the above listed status values are not exhaustive and may vary depending on the payment method.

11

Payment Method

ans..64

Payment method (e.g. Barzahlen, Card, PayPal etc.)

12Payment Typeans..64Payment type (e.g., 3X, 4X, etc..)

13

Card Brand

a..22

Card scheme (e.g. Visa, MasterCard, Maestro etc.)

14

Country of Origin Card A2

a..2

Country of origin according to BIN/IIN (2 characters or n/a, e.g. DE)

15

Country of Origin Card A3

a..3

Country of origin according to BIN/IIN (3 characters or n/a, e.g. DEU)

16

Country of Origin Card N3

an..3

Country of origin according to BIN/IIN (3 digits or n/a, e.g. 276)

17

Card Number

an..19

Masked card number

18

Card Token

n..19

Card token generated by

19SchemeReferenceIDans..64Unique transaction identifier provided from the card scheme

20

Expiry daten6Credit card's expiry date in the format yyyyMM, e.g. 202005

21

Approval codean6Authorisation code of the transaction

22

Cardholder Nameans..60Name of cardholder

23

CardTypeans..64Card type, e.g. Credit, Debit, Prepaid,...

24

Category (Card)ans..64Credit card category, e.g. Standard, Business,...

25

SubBranda..22CardBrand2 or Sub-Brand

26

BINn6..11Bank Identification Number

27

TerminalIDan7..8ID of the terminal

28

POS TerminalIDan..12ID of the physical terminal (device)

29

CardAcceptorIDn5..12Contract partner number

30

Acquirer Namean..5Acquirer shortcode

31

IBAN

an..30

International Bank Account Number

32

BIC

an..11

ISO 9362 Business Identifier Code

33

User Data

ans..256

Custom merchant data that are included in the response and that might get conveyed to the subsequent processing host depending on the acquirer and custom arrangements

34

OrderDesc

an..768

Order description

35

ActionID

an..64

Unique action identifier assigned by

36

Payment Action

a..30

Specifies the action performed on the payment:

·         AUTHENTICATE: authentication for a payment

·         AUTHORIZE: authorize of a payment

·         CAPTURE: capture of an authorized payment

·         CREDIT: credit of a payment

·         SALE: authorize and capture of a payment

·         CHARGEBACK: chargeback of a previously made payment

For chargebacks it depends on acquirer whether they are notified in EPA and can be attributed to a payment process.

37

Action Date

ans19

Timestamp of  the action: DD.MM.YYYY hh:mm:ss

38

Reference number (Transaction)ans..30Additional Transactions-ID from the merchant on action level

39

Card holder information 1 (Transaction)ans..64Text printed on the customer’s credit card bill alongside the payee

40

Card holder information 2 (Transaction)ans..64Text printed on the customer’s credit card bill alongside the payee

41

Response Code

n8

response code

42

Action Status

a..50

Status received on the performed action

43

Action Amount

n..10

Operation amount in its smallest unit of transaction currency

44

Code Description

an..1024

Error code description

45

EPA date (transaction)ans..19Timestamp when EPA file has been processed

46

EPA status (transaction)a..3Status of EPA processing