Smart Data Reference Guide |
|---|
Guide d'intégration |
Version 1.0 |
Date 17/03/2020 |
Table des matières
| Table of Contents |
|---|
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.
DataFormats des données
| Format | Description |
|---|---|
a |
Alphabétique |
as |
Alphabétique avec caractères spéciaux |
n |
Numérique |
an |
Alphanumérique |
ans |
Alphanumérique avec caractères spéciaux |
ns |
Numérique avec caractères spéciaux |
bool |
Expression |
booléenne (vrai ou faux) |
3 |
Longueur fixe avec 3 chiffres/caractères |
..3 |
Longueur variable avec maximum 3 |
chiffres/ |
caractères |
enum |
Énumération de valeurs admissibles |
dttm |
Date et heure ISO (AAAA-MM- |
JJThh:mm:ss) |
Définitions
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.
Veuillez noter que les termes « paiement » et « transaction » sont utilisés de façon interchangeable dans le présent document. Un paiement – ou une transaction – peut englober un certain nombre d'activités opérationnelles. Dans un cycle de vie de transaction, le statut de la transaction change en fonction de l'action effectuée. Parmi ces actions figurent l'autorisation, la saisie, la vente, l'annulation et le remboursement. Une transaction est ainsi définie comme une séquence d'actions. | |
Action | Une action consiste en une opération qui modifie le statut d'un paiement lorsqu'elle est exécutée avec succès. |
Job | Dans le cadre de BNP Smart Data, un job inclut un ensemble d'informations générales sur la présentation du rapport, les options de filtrage et les champs de données. |
Task | Une tâche constitue la représentation réelle d'un job avec un temps d'exécution attribué. |
Présentation du produit
BNP Smart Data est un service automatisé conçu pour créer un ou plusieurs rapport(s) prédéfini(s) mis à disposition dans le compte FTP d'un commerçant à des fins de récupération. Ce service permet aux commerçants de programmer des rapports périodiques en fonction de leurs besoins individuels.
Les rapports Smart Data sont fournis sous forme de fichiers texte délimités (CSV) avec un ensemble standard de champs de données par défaut. Les commerçants ont néanmoins la possibilité de personnaliser leurs rapports en sélectionnant les champs de l'ensemble standard qu'ils souhaitent inclure. Les enregistrements peuvent englober des données relatives à des transactions effectuées entre un jour et maximum un an avant la date du rapport. À noter que les données en temps réel ne sont pas prises en charge par ce produit.
Pour toute configuration individuelle, veuillez contacter le service d'assistance BNP.
Filtrage des rapports
Les options de filtrage suivantes sont disponibles :
- MerchantID
- Société
- Devise
- Mode de paiement
- Statut du paiement
- Marque de la carte
- Action
- Uniquement les transactions réussies
- Uniquement les transactions non réussies
- Uniquement les transactions avec code(s) spécifique(s)
- Uniquement les transactions sans code(s) spécifique(s)
Veuillez noter que toutes les options de filtrage sont susceptibles de contenir plusieurs valeurs.
Planification des rapports
Les rapports Smart Data peuvent être configurés selon les options suivantes :
Rapport unique
- Période donnée entre deux dates
Rapports périodiques
- Tous les jours
- Toutes les semaines (jour de livraison en semaine à la seule discrétion du commerçant)
- Tous les mois (le 1er, le 2, le 3, ... du mois)
Format de fichiers
Les rapports BNP Smart Data sont créés dans des fichiers CSV sous forme de texte brut. Les virgules, les tabulations et les deux points sont des séparateurs pris en charge pour séparer des valeurs (pour toute configuration individuelle, veuillez contacter le service d'assistance BNP). Sauf indication contraire, les deux points sont utilisés comme séparateur par défaut.
Chaque fichier contiendra une première ligne d'en-tête et zéro ou plusieurs ligne(s) de données. Une ligne d'en-tête sera constituée d'une liste séparée des différents noms de champs, tels que définis dans le présent document, dans la commande spécifiée. Les noms des champs de la ligne d'en-tête sont actuellement disponibles en anglais et en allemand. Les lignes de données consistent en une liste séparée des valeurs des champs de données qui contiennent des caractères codés en UTF-8.
Sécurité
Pour des raisons de sécurité, tous les fichiers sont chiffrés (PGP) et transférés via SFTP.
Noms de fichier
Les noms de fichiers sont attribués selon la convention suivante
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]_[YYYYMMDDAAAAMMJJ_hhmmss].CSV.pgp
The individual name elements are described in the table belowLes différents éléments du nom sont décrits dans le tableau ci-dessous.
# | ElementÉlément | Format | ExampleExemple |
|---|---|---|---|
1 | PrefixPréfixe | a12 | BNPSmartData |
2 | JobID | n..10 | Internal Identifiant interne du job identifier |
3 | TaskID | n..10Internal | task identifierIdentifiant interne de la tâche |
4 | TimestampHorodatage | an15 | YYYYMMDDAAAAMMJJ_hhmmss |
A valid file name example isExemple de nom de fichier valide : BNPSmartData_12_789_20160320_023609.CSV.pgp
Enregistrements de données et description des champs
Chaque enregistrement représente une opération/action effectuée sur un paiement. En règle générale, un paiement se compose de plusieurs enregistrements d'opérations. Les champs de données disponibles sont répertoriés dans le tableau ci-dessous. Les champs de données individuels peuvent être omis sur demande.
# | Paramètre |
|---|
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..32Payment identifier generated by Payment platform | Identifiant de paiement généré par la plate-forme de paiement |
02 | MerchantID | an..20 | Merchant identifier assigned by Identifiant de commerçant attribué par BNP |
03 | Payment Date | ans19 | Timestamp of payment creation time: DDHorodatage de l'heure de création du paiement : JJ.MM.YYYY AAAA hh:mm:ss |
04 | TransID | ans..64Transaction identifier assigned by the merchant on payment level | Identifiant de transaction attribué par le commerçant au niveau du paiement |
05 | RefNr | ans..30 | Supplementary transaction identifier assigned by merchant on payment levelIdentifiant de transaction supplémentaire attribué par le commerçant au niveau du paiement |
06 | Amount Auth | n..10 | Authorized amount in its smallest unit of transaction currencyMontant autorisé dans la plus petite unité de la devise de transaction |
07 | Amount Cap | n..10 | Captured amount in its smallest unit of transaction currencyMontant saisi dans la plus petite unité de la devise de transaction |
08 | Amount Cred | n..10 | Refunded amount in its smallest unit of transaction currencyMontant remboursé dans la plus petite unité de la devise de transaction |
09 | Currency | a3 | Code pour la devise, trois caractères ISO 4217 three-letter currency code |
10 | Payment Status | a..30 | Transaction status with one of the following valuesStatut de la transaction avec l'une des valeurs suivantes : · AUTHORIZED · CANCELED · CAPTURE_REQUEST · CREDIT_REQUEST · FAILED · OK · PENDING · SUCCESSPlease note that the above listed status values are not exhaustive and may vary depending on the payment method Veuillez noter que les valeurs de statut susmentionnées ne sont pas exhaustives et peuvent varier en fonction du mode de paiement. |
11 | Payment Method | ans..64 | Payment method (e.g. Barzahlen, Card, PayPal Mode de paiement (par ex. liquide, carte, PayPal, etc.) |
12 | Card Brand | a..22 | Card scheme (e.g. Système de cartes (par ex. Visa, MasterCard, Maestro, etc.) |
13 | Country of Origin Card A2 | a..2 | Country of origin according to Pays d'origine selon BIN/IIN (2 characters or caractères ou n/a, e.gpar ex. DE) |
14 | Country of Origin Card A3 | a..3 | Country of origin according to Pays d'origine selon BIN/IIN (3 characters or caractères ou n/a, epar ex. g. DEU) |
15 | Country of Origin Card N3 | an..3 | Country of origin according to Pays d'origine selon BIN/IIN (3 digits or chiffres ou n/a, e.gpar ex. 276) |
16 | Card Number | an..19 | Masked card numberNuméro de carte masqué |
17 | Card Token | n..19Card token generated by Payment platform | Token de carte généré par la plate-forme de paiement |
18 | Expiry Date | n6 | Credit card's expiry date in the format yyyyMM, e.g. Date d'expiration de la carte de crédit au format aaaaMM, par ex. 202005 |
19 | Approval Code | an6Authorisation | code of the Code d'autorisation de la transaction |
20 | Cardholder Name | ans..60Name of cardholder | Nom du titulaire de la carte |
21 | CardType | ans..64 | Card type, e.g. Credit, Debit, PrepaidType de carte, par ex. crédit, débit, prépayée, ... |
22 | Category (Card) | ans..64 | Credit card category, e.g. Standard, BusinessCatégorie de carte de crédit, par ex. standard, business,... |
23 | SubBrand | a..22 | CardBrand2 or Subou sous-Brandmarque |
24 | BIN | n6..11Bank | Identification NumberNuméro d'identification bancaire |
25 | IBAN | an..30International | Bank Account NumberNuméro de compte bancaire international |
26 | BIC | an..11 | ISO 9362 Business Identifier Code d'identification des banques |
27 | User Data | ans..256Custom 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 | Données personnalisées du commerçant qui sont incluses dans la réponse et qui pourraient être transmises à l'hôte de traitement suivant en fonction de l'acquéreur et des dispositions spécifiques |
28 | OrderDesc | an..768 | Order descriptionDescription de la commande |
29 | ActionID | an..64Unique action identifier assigned by Payment platform | Identifiant d'action univoque attribué par la plate-forme de paiement |
30 | Payment Action | a..30Specifies | the action performed on the paymentAction effectuée pour le paiement |
31 | Action Date | ans19 | Timestamp of the action: DDHorodatage de l'action : JJ.MM.YYYY AAAA hh:mm:ss |
32 | Response Code | n8 | Code de réponse Paygate response code |
33 | Action Status | a..50 | Status received on the performed actionStatut reçu pour l'action exécutée |
34 | Action Amount | n..10 | Operation amount in its smallest unit of transaction currencyMontant de l’opération dans la plus petite unité de la devise de transaction |
35 | Code Description | an..1024 | Error code descriptionDescription du code d'erreur |