Smart Data Reference Guide |
|---|
Guide d'intégration |
Version 1.0 |
Date 17/03/2020 |
Table des matières
Historique des versions
Date | Nom | Modification |
|---|---|---|
17/03/2020 | Peter Posse | Version originale |
À propos de ce guide
Ce guide sert de référence pour le format et le contenu des rapports générés et fournis via le produit BNP Smart Data.
Public cible
Ce document est destiné au personnel technique qui récupérera et analysera les rapports générés par le système BNP Smart Data.
Data Formats
| Format | Description |
|---|---|
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/ | 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 BNP 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
BNP 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 the BNP helpdesk.
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
BNP 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 BNP helpdesk 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: BNPSmartData_[JobID]_[TaskID]_[YYYYMMDD_hhmmss].CSV.pgp
The individual name elements are described in the table below.
# | Element | Format | Example |
|---|---|---|---|
1 | Prefix | a12 | BNPSmartData |
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: BNPSmartData_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 Payment platform |
02 | MerchantID | an..20 | Merchant identifier assigned by BNP |
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.) |
12 | Card Brand | a..22 | Card scheme (e.g. Visa, MasterCard, Maestro etc.) |
13 | Country of Origin Card A2 | a..2 | Country of origin according to BIN/IIN (2 characters or n/a, e.g. DE) |
14 | Country of Origin Card A3 | a..3 | Country of origin according to BIN/IIN (3 characters or n/a, e.g. DEU) |
15 | Country of Origin Card N3 | an..3 | Country of origin according to BIN/IIN (3 digits or n/a, e.g. 276) |
16 | Card Number | an..19 | Masked card number |
17 | Card Token | n..19 | Card token generated by Payment platform |
18 | Expiry Date | n6 | Credit card's expiry date in the format yyyyMM, e.g. 202005 |
19 | Approval Code | an6 | Authorisation code of the transaction |
20 | Cardholder Name | ans..60 | Name of cardholder |
21 | CardType | ans..64 | Card type, e.g. Credit, Debit, Prepaid,... |
22 | Category (Card) | ans..64 | Credit card category, e.g. Standard, Business,... |
23 | SubBrand | a..22 | CardBrand2 or Sub-Brand |
24 | BIN | n6..11 | Bank Identification Number |
25 | IBAN | an..30 | International Bank Account Number |
26 | BIC | an..11 | ISO 9362 Business Identifier Code |
27 | 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 |
28 | OrderDesc | an..768 | Order description |
29 | ActionID | an..64 | Unique action identifier assigned by Payment platform |
30 | Payment Action | a..30 | Specifies the action performed on the payment |
31 | Action Date | ans19 | Timestamp of the action: DD.MM.YYYY hh:mm:ss |
32 | Response Code | n8 | Paygate response code |
33 | Action Status | a..50 | Status received on the performed action |
34 | Action Amount | n..10 | Operation amount in its smallest unit of transaction currency |
35 | Code Description | an..1024 | Error code description |