Table des matières
Acronymes et abréviations
Formats des données : 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 (true ou false) 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) Abréviations : CND condition M obligatoire (mandatory en anglais) O optionnel C conditionnel Remarque : Veuillez noter que les noms des paramètres peuvent être en majuscules ou en minuscules.
Fichiers Batch
Le paiement via Batch consiste à transférer les données des transactions collectées des clients vers le serveur Axepta BNP Paribas sous forme de fichiers formatés. Le transfert peut se faire :
- Manuellement via le back-office de BNP Paribas. (Se référer à la documentation Backoffice)
- Automatiquement via un protocole de transfert sécurisé (sFTP).
Lors de ce processus, vous associez les données des transactions (comme l’identifiant, le montant et la devise) dans un fichier batch que vous transmettez ultérieurement à la solution de paiement. La solution de paiement procède ensuite aux paiements et enregistre le statut de transaction dans le fichier batch de retour. Après traitement, le commerçant peut télécharger le fichier batch avec les détails sur le statut de la transaction.
L’accès sFTP pour le transfert du fichier batch doit être demandé à l’Assistance BNP Paribas.
Les fichiers batch doivent être correctement structurés pour que la solution de paiement puisse les traiter.
Nom des fichiers Batch
Le nom d’un nouveau fichier batch commence par une lettre indiquant la phase. Par exemple T pour indiquer que le fichier vient d’être transféré. Il est suivi de la date de soumission au format AAAAMMJJ. Par exemple : 20160112. Celle-ci est suivie d’un décompte à trois chiffres qui commence à 001 et de l’identifiant du commerçant émis par BNP Paribas. Si vous soumettez plusieurs fichiers le même jour, vous devez définir le décompte sur 002, 003, 004, etc. L’extension du fichier doit être .DAT.
Le nom d’un fichier batch comprend donc quatre composants :
<Phase><Date><MerchantID><Counter>.dat |
Le nom d’un fichier batch via FTP :
<Phase><Date><Counter><MerchantID>.dat |
Composant | Description |
|---|---|
Phase | T=Transféré, P= Traité (Processed en anglais) |
Date | Date au format AAAAMMJJ (année, mois, jour) |
Counter | Trois chiffres, décompte journalier de 001 à 999. |
| MerchantID | Identifiant du commerçant (MID) |
Le traitement du fichier batch passe par plusieurs phases indiquées dans le nom du fichier : le fichier d’origine du commerçant débute par le caractère T pour « transféré ». Après traitement, le fichier batch comporte le suffixe P (pour processed)
Si un commerçant (ayant le MerchandID : MerchantID) soumet deux fichiers batch le même jour, ces deux fichiers sont nommés comme suit :
T20160112001MerchantID.dat |
Remarque : après que vous ayez transmis le fichier batch, le traitement des transactions débute. Après transmission et durant le traitement, le préfixe W (Waiting, en attente) est ajouté au fichier. Si le fichier batch est soumis via FTP/sFTP pour traitement, la phase doit être renommée W après l’upload par le système du commerçant. Le traitement commence uniquement après cette étape.
W20160112001MerchantID.dat |
Lorsque toutes les transactions de paiement ont été effectuées, la solution de paiement marque les fichiers traités, qui contiennent désormais les détails du statut de transaction, avec la lettre P pour « Processed » (traité) et auxquels vous pouvez accéder dans la vue par batch du back office BNP Paribas via un téléchargement :
P20160112001MerchantID.dat |
Transfert FTP de fichiers Batch
La solution de paiement vous permet de transférer des fichiers batch automatiquement via FTP (File Transfer Protocol). Pour transférer un fichier batch via FTP/sFTP, procédez comme suit :
- Enregistrer les données de transaction dans un fichier batch formaté
- Chiffrer le fichier batch
- Transférer le fichier batch
- Changer de phase après chargement (T ® W)
- Récupérer le fichier batch après traitement
- Vérifier le statut des transactions
Chiffrement du fichier Batch
Pour des raisons de sécurité, les fichiers batch doivent être chiffrés avant la transmission FTP/sFTP. Pour garantir un niveau de sécurité maximum, la solution de paiement utilise un chiffrement asymétrique avec PGP (Pretty Good Privacy). Le chiffrement avec GPG (GNU Privacy Guard) est également possible. Le fichier enregistré doit toutefois avoir l’extension .PGP, sans quoi aucun traitement n’est possible.
Le haut niveau de sécurité du chiffrement PGP repose sur un processus avec deux clés : une clé privée et une clé publique. BNP Paribas vous fournit une clé publique pour le chiffrement de votre fichier batch. Le fichier batch chiffré peut ensuite être déchiffré uniquement avec la clé secrète privée de BNP Paribas.
Vous pouvez également générer une clé publique et une clé privée pour votre entreprise. La solution de paiement chiffre le fichier batch avec votre clé publique. Le fichier peut ensuite être lu uniquement avec votre clé privée secrète.
Format des fichiers Batch
Un fichier batch comprend un en-tête (Header), plusieurs enregistrements et un pied de page (footer). Chaque entrée du fichier correspond à une ligne complétée avec CRLF (touche Entrée). Les valeurs dans une ligne sont séparées par des virgules. Il s’agit du format CSV (Comma Separated Values, valeurs séparées par une virgule).
Les sections suivantes décrivent le format du fichier batch que vous transmettez à la solution de paiement et le fichier de réponse, dans lequel la solution de paiement enregistre les résultats des paiements.
Format des fichiers Batch soumis
Remarque : le fichier batch ne doit pas inclure de lignes vides au début et à la fin du fichier. Les lignes vides dans les listes sont uniquement prévues pour faciliter la lecture.
Remarque : les paramètres comme « Reason » ou « OrderDesc » peuvent ne pas contenir de virgules.
Remarque : dans les versions batch 2.x, il existe un autre champ pour <MID>. Il est donc possible pour un paramètre MasterMID de soumettre les transactions d’un SubMID
En-tête
Type,MerchantID,Date,Version |
Enregistrement
Type,Action,<Amount>,<Currency>,<TransID>,<Data depends on Action> |
Pied de page
Type,CountRecords,SumAmount |
L’exemple suivant représente un fichier batch pour la capture de trois transactions par carte avec une valeur de 1,00 et 2,00 euros. Pour le premier paiement, le système du commerçant fournit le numéro de référence 123456, mais aucun numéro de référence n’est fourni pour le deuxième et le troisième :
HEAD,MerchantID,20160112,1.2 CC,Sale,100,EUR,1567890,123456,MasterCard,5490011234567890,200506,Your order from Jan. 4. CC,Sale,100,EUR,1567891,,MasterCard,5490011234567890,200506,Your order from Jan. 4. CC,Sale,200,EUR,10202280,,VISA,4907621234567890,200504,Your order from Jan. 4. FOOT,3,400 |
La description de chaque champ et valeurs du jeu de données (Enregistrements/RECORDS) dans le fichier batch est disponible dans le chapitre correspondant du manuel sur la méthode de paiement.
Les paramètres généraux pour le transfert dans l’en-tête et le pied de page sont expliqués dans le tableau suivant :
Paramètre | Format | CND | Description |
|---|---|---|---|
Type | a..11 | M | « HEAD » pour en-tête (Header), « FOOT » pour pied de page (Footer) et, par exemple, « CC » pour carte. Le champ n’a pas à contenir 11 chiffres. |
MerchantID | ans..30 | M | Identifiant du commerçant (MID) fourni par BNP Paribas |
Date | dttm8 | M | Date de production du fichier au format AAAAMMJJ |
Version | an6 | M | La version batch utilisée détermine les paramètres facultatifs utilisés en addition. Les versions batch possibles dans chaque cas diffèrent selon la méthode de paiement et l’action effectuée. Vous trouverez les versions possibles dans le chapitre sur les fichiers batch de la méthode de paiement correspondante. |
CountRecords | n..5 | M | Nombre d’enregistrements soumis sans en-tête (header) ni pied de page (footer) |
SumAmount | n..12 | M | Total des montants dans l’unité de devise la plus faible, p. ex. centimes dans le cas des euros, selon le tableau des devises. Contactez l’Assistance si vous voulez capturer des montants inférieurs à 100 (unité de devise la plus faible). |
Format des fichiers de reponse Batch
Lors du traitement des transactions, le gestionnaire des fichiers batch enregistre le statut de la transaction dans le fichier batch. Dans cette optique, les champs de statut et de code sont ajoutés dans les entrées de transaction dans la zone d’enregistrement (Record):
Enregistrement (Record)
CC,Capture,<Amount>,<Currency>,<TransID>,<RefNr>,<PayID>,<Status>,<Code> |
Remarque : en règle générale, le retour des paramètres facultatifs dans le fichier de réponse se produit uniquement si ceux-ci étaient inclus dans le fichier soumis. En règle générale, aucune information d’envoi n’est fournie dans le fichier de réponse. Si vous avez à nouveau besoin de ces données, lisez-les à partir du paramètre de notification correspondant.
Les paramètres de réponse particuliers que le gestionnaire des fichiers batch enregistre dans la section d’enregistrement pour chaque transaction sont disponibles dans le chapitre relatif aux fichiers batch pour la méthode de paiement concernée.
Codes retours Batch
La solution de paiement prend en charge les codes d’erreur détaillés depuis la version 3.0. Il s’agit de codes hexadécimaux à huit chiffres. La structure et la signification des codes d’erreur sont décrites sur la base de l’exemple suivant :
2 105 0014 |
Le premier chiffre décrit le niveau de gravité de l’erreur. Toutes les valeurs supérieures à 0 indiquent un avertissement ou une erreur.
Remarque : un code d’erreur ne signifie pas nécessairement que la solution de paiement ou le système du commerçant a subi une erreur technique. La solution de paiement génère également un code d’erreur si une transaction a échoué car la banque refuse un paiement.
Les 2e, 3e et 4e chiffres du code d’erreur décrivent la catégorie de l’erreur. Les catégories d’erreur se rapportent aux erreurs de chiffrement (001) et de format (010), et aux détails des méthodes de paiement, initiés dans le cas des cartes (100) à débit immédiats (110) ou Cash&Go (140).
Les chiffres 5 à 8 du code d’erreur fournissent une indication sur les détails de l’erreur : instructions sur les problèmes de configuration comme des identifiants de terminaux manquants (0047) et dysfonctionnements au niveau du centre informatique de la banque du porteur de carte (121), mais également des refus standard de paiements par carte en cas de cartes expirées (110) ou de messages refusés (0100).
Remarque : les transactions sans erreur, pour des raisons de compatibilité avec la version 2.1, ne sont pas spécifiées par un 8, mais un zéro (0).
Vous trouverez la liste complète des codes d’erreur de la solution de paiement dans le fichier Excel.
Appels et réponses de Batch
Cette section décrit les paramètres qui doivent être transférés dans les enregistrements (Records) pour l’exécution d’un paiement par carte, et quelles informations peuvent être trouvées dans le fichier de réponse sur le statut du paiement.
La structure pour un paiement par carte dans un fichier batch à soumettre est la suivante :
HEAD,<MerchantID>,<Date>,<Version> CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>] CC,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,[<FinishAuth,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>] CC,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[,<FinishAuth>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,CreditEx,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID> FOOT,<CountRecords>,<SumAmount> |
Exemple de versions batch :
Version 1.2: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc> CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder> Version 1.2.1: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder> Version 1.3: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCCVC>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF> Version 1.5: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<Zone> |
Le tableau suivant décrit les champs et valeurs utilisés dans le jeu de données (Record (enregistrement)) dans le fichier batch :
Paramètre | Format | CND | Description |
|---|---|---|---|
Type | a..11 | M | « HEAD » pour en-tête (header), « FOOT » pour pied de page (footer), « CC » pour carte |
Action | a..20 | M | Le paramètre Action définit le type de la transaction : Authorize (autorisation) Capture Sale Refund CreditEx (remboursement sans capture ; convenez de cela au préalable avec le Support BNP Paribas) Reverse (annulation) AuthSplit (capture partielle) Renewal (renouvellement d’autorisation) |
Amount | n..10 | M | Montant dans l’unité de devise la plus petite (p. ex. centime d’euro). Contactez l’Assistance si vous voulez capturer des montants inférieurs à 100 (unité de devise la plus faible). |
Currency | a3 | M | Code de devise, trois chiffres DIN / ISO 4217 |
TransID | ans..64 | M | Identifiant de la transaction devant être unique pour chaque paiement. Notez pour certaines connexions, les différents formats fournis au sein des paramètres spécifiques. |
RefNr | an12 | M | Numéro de référence unique |
PayID | an32 | M | Identifiant de cette transaction fournie par la solution de paiement |
OrderDesc | ans..127 | O | Description des produits achetés, prix à l’unité, etc. |
CCBrand | a..22 | C | Marque de la carte. Notez bien l’orthographe ! Selon le tableau des marques de carte ! |
CCNr | n..16 | C | Numéro de carte d’au moins 12 chiffres, numériques sans espace. Vous pouvez également transmettre un TOKEN (numéro de carte temporaire) |
PCNr | n..16 | O | Vous pouvez également transmettre un TOKEN (PCN) au lieu du numéro de carte réelle. |
CCCVC | n..4 | O | Vérification de carte : dans le cas de Visa et MasterCard, les 3 derniers chiffres sur la bande de signature de la carte. 4 chiffres dans le cas d’American Express. |
CCExpiry | n6 | O | Date d’expiration de la carte au format AAAAMM, p. ex. 201707. |
FinishAuth | ans1 | O | Version=1.4 : si vous utilisez le renouvellement d’autorisation, annulez la répétition avec la valeur Y dans le champ FinishAuth dans le cas d’une capture ou d’un remboursement. Exemple : vous capturez une livraison partielle. Le reste de la commande ne peut pas être fourni. Vous saisissez par conséquent Y dans le champ FinishAuth pour une capture partielle, afin que la solution de paiement n’autorise pas le montant restant. |
| RTF | a1 | O | Abonnement à durée et montant fixes
Abonnement à durée et montants variables
|
La zone d’enregistrement dans le fichier de réponse pour les transactions par batch se présente comme suit :
HEAD,<MerchantID>,<Date>,<Version> CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>],<Status>,<Code> CC,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>],<Status>,<Code> CC,AuthSplit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,FAILED,<Code>,<Description>,[<PCNr>] CC,Renewal,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,FAILED,<Code>,<Description>,[<PCNr>] CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>],<Status>,<Code> CC,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[,<FinishAuth>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>],<Status>,<Code> CC,CreditEx,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>],<Status>,<Code> CC,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<Status>,<Code> FOOT,<CountRecords>,<SumAmount> |
Le tableau suivant décrit les paramètres de réponse que le gestionnaire des fichiers batch enregistre dans la zone d’enregistrement (record) pour chaque transaction (paramètres standard non expliqués ici, comme <TransID> ou <RefNR>, et les paramètres de requête sont retournés non modifiés et correspondent à l’appel tel que spécifié auparavant) :
Paramètre | Format | CND | Description |
|---|---|---|---|
Action | a..20 | M | Le paramètre Action définit le type de la transaction : capture ou remboursement (voir ci-dessous). |
PayID | an32 | M | Identifiant de cette transaction fournie par la solution de paiement |
Status | a..50 | M | OK ou FAILED (échec) |
Code | n8 | M | Code d’erreur selon les codes de réponses de la solution de paiement |
PCNr | n..16 | C | Le TOKEN est uniquement retourné dans le cas des types de transaction Authorize ou Sale et RefundEx. Il commence par 0 et les 3 derniers chiffres correspondent à ceux du véritable numéro de carte. |