Table des matières

Historique des versions

Acronymes et abréviations

Introduction

La plateforme solution de paiement Axepta BNP Paribas accepte les ordres de paiement, traite les données et exécute les transactions de paiement du commerçant en toute sécurité.

Ce manuel décrit l’intégration de la plateforme solution de paiement Axepta BNP Paribas au système du commerçant et s’adresse aux développeurs et aux responsables techniques.

Principes majeurs de la programmation de la

solution

Afin d’envoyer les ordres de paiement à la plateforme solution de paiement Axepta BNP Paribas, le commerçant:

• Se connecte via Internet à la plateforme solution de paiement Axepta Online
• Envoie les données de paiement requises dans un format homogène

Pour garantir la compatibilité avec tous les langages de programmation et tous les systèmes d'exploitation (Linux, Unix, Windows), la plateforme solution de paiement Axepta BNP Paribas élimine la nécessité d’avoir recours à un logiciel de compatibilité sur le serveur du commerçant. L’installation logicielle entraîne généralement des problèmes avec les versions des systèmes d’exploitation ou les règles de sécurité.

Quelle que soit la méthode de paiement choisie, les paramètres envoyés sont toujours les mêmes. Cela afin que toutes les méthodes de paiement fonctionnent de la même manière et ne nécessitent aucun effort supplémentaire.

Afin de garantir le stockage sécurisé des données de paiement, les réseaux ont élaboré un programme de sécurité avec la certification de sécurité PCI (Payment Card Industry). L'emplacement où les données de paiement sont enregistrées est crucial pour la sécurité des paiements sur internet.

Intégration de la

solution de paiement Axepta Online

La plateforme solution de paiement propose 4 options d’intégration différentes :

• Paiement via le formulaire de la page de paiement 
• Paiement via la connexion server-to-server 
• Paiement par batch 
• Paiement via In-App (SDK Mobile)

Formulaires de la page de paiement

Le

formulaire de la page de paiement et les

données de paiement sont

hébergés par Axepta

Cette option est la méthode la plus simple et la plus rapide pour intégrer la solution.

La plateforme solution de paiement fournit des formulaires HTML avec chiffrement TLS et certifiés SSL. Le site web doit uniquement appeler le « formulaire HTML » de la plateforme solution de paiement pour le faire apparaitre apparaître soit en redirection complète, soit en iFrame, soit en lightbox (pop-up). Ce choix dépend du commerçant. Ensuite, les acheteurs saisissent leurs informations de paiement via ce formulaire HTML. Ces données seront transférées via une requête HTTP POST en tant que paramètres d’URL (URL : payssl.aspx).

Le commerçant doit uniquement se conformer au formulaire PCI- SAQ A.

Le formulaire de la page de paiement est héberge par le commerçant et les

données de paiement sont

hébergés par Axepta

Cette option (appelée également « Silent order post » ou « Direct post ») donne plus de contrôle au commerçant puisque c’est à lui d’afficher directement le formulaire de la page de paiement sur son site. Le commerçant peut alors développer son propre modèle de page de paiement et l’héberger sur son serveur. Il va afficher la page de paiement lorsque l’acheteur validera son panier et envoyer les données de paiement directement au serveur d’AXEPTA BNP Paribas.

Ces données peuvent être capturées sur le site web du commerçant sans être traitées par le serveur du commerçant, d’où l’intérêt d’envoyer la requête POST en mode silencieux vers le serveur Axepta BNP PARIBAS (URL : paynow.aspx) comprenant les données en tant que paramètres de saisie du formulaire et non pas en tant que paramètres d’URL comme c’est le cas lors de l’appel payssl.aspx.

Afin d’utiliser cette option, le commerçant doit respecter l’exigence PCI relative au SAQ A-EP.

A noter : Les tentatives de reconnexion automatique à la plateforme solution de paiement doivent être désactivées en utilisant le mode « paynow » car la plateforme solution de paiement ne peut pas renvoyer l’acheteur vers la page de paiement précédente du commerçant. Veuillez contacter le support de BNP Paribas pour effectuer la désactivation.

Demander le formulaire de page de paiement BNP Paribas

La demande d’un formulaire de la plateforme solution de paiement débute avec la composition correcte des paramètres comprenant une clé et une valeur séparés séparées par le signe égal (=). Il s’agit de la méthode NVP (Name-Value-Pairs) :

Tous les paramètres sont assemblés pour former une chaîne de caractères et séparés par le caractère & :

Remarque : les caractères « = » et « & » étant utilisés en tant que caractères de séparation, ils ne peuvent pas être transmis comme des valeurs. Toutes les valeurs que vous transmettez sans chiffrement Blowfish doivent être encodées au format URL.

Une chaîne de caractères correcte pour la plateforme solution de paiement contient trois paramètres de base : MerchantID (Identifiant du commerçant), Len (Longueur) et Data (Données). Les paramètres MerchantID et Len ne sont pas chiffrés. Seul le paramètre Data est chiffré avec la méthode Blowfish :

Le paramètre Data (Données) comprend les détails de paiement essentiels comme le montant et la devise.

Le paramètre Len (Longueur) est très important pour le chiffrement, car il contient la longueur de la chaîne de caractères non chiffrée dans le paramètre Data. La quantité de données à chiffrer étant multipliée par 8 dans le cas du chiffrement Blowfish, la longueur correcte de la chaîne de caractères doit être connue pour le déchiffrement, sans quoi d’autres caractères non prévus apparaissent à la fin de la chaîne de caractères.

Les paramètres sont transmis via HTTPS POST ou HTTPS GET. La méthode de transmission recommandée est HTTPS POST, car la chaîne de caractères du paramètre dans le cas de GET, jointe à l’URL, est limitée à 2 048 octets selon le navigateur, contrairement à la méthode POST qui n’est pas limitée par la taille de l’URL.

Remarque : la longueur maximale d’une requête de paiement est limitée à 5120 caractères. Si vous devez utiliser des chaînes plus longues, contactez le Support BNP Paribas.

Le développement d’une requête de paiement, sans chiffrement, pourrait être représenté comme suit :

Remarque : une valeur doit être attribuée à chaque paramètre. Ne transmettez pas de paramètres vides, car cela peut entraîner l’échec du paiement.

Cette chaîne de caractères est ensuite chiffrée et transmise en tant que paramètre Data (Données) et se présente comme suit :

Remarque : Les paramètres sont transmis non chiffrés pour garantir la bonne mise en page du formulaire.

Un formulaire HTML est produit pour HTTPS POST et tous les paramètres sont transmis en tant que champs masqués. Seul le bouton « Payer » est visible pour le client :

Authentification Hash MAC

Pour vous protéger de toute manipulation non autorisée de vos transactions de paiement, la plateforme solution de paiement AXEPTA BNP Paribas vérifie si votre requête de paiement est authentique grâce à l’authentification HMAC (Hash Message Authentication Code). Vous devrez donc transférer une valeur HMAC à la plateforme solution de paiement pour chaque transaction dans le paramètre MAC.

NB: il existe une méthode de décodage pour chaque méthode d’encodage et quiconque possédant la clé correcte ou brisant le chiffrement peut lire et manipuler les données. Par conséquent, aucune méthode de chiffrement n’est sûre à 100 %. Cependant avec la procédure Hash en revanche, le décodage est impossible et la valeur Hash permet de confirmer formellement l’authenticité du message.

La plateforme solution de paiement utilise un code HMAC (Hash Message Authentication Code) pour vérifier l’authenticité de vos paiements. L’algorithme MAC SHA-256 est utilisé avec une clé de 32 chiffres (256 bits).  Un mot de passe supplémentaire renforce la sécurité de la procédure HMAC.

Le tableau suivant décrit la méthode de génération des valeurs Hash pour votre paiement :

Remarque : Si le paramètre MAC a été transféré avec la première transaction (demande d’autorisation), il est obligatoire pour toutes les transactions suivantes (ex. capture, remboursement, etc).

Important : La plateforme solution de paiement rejette immédiatement les transactions avec des valeurs HMAC erronées ou manquantes sans autre traitement, car il s’agit probablement d’un piratage. Par conséquent, les transactions que la plateforme solution de paiement rejette avec les codes d’erreur 20100044 ou 20120044 n’apparaissent pas dans le back office Axepta BNP Paribas (Se référer au document regroupant les codes retours).

Le site web du commerçant doit vérifier que la notification de paiement provient réellement de BNP Paribas. En effet, un fraudeur peut initialiser une transaction et falsifier cette notification. Par conséquent, le système du commerçant doit le faire automatiquement.

Actuellement, la requête de notification est uniquement chiffrée. Toutefois, ce chiffrement ne garantit pas l’authenticité d’un message. Cela garantit uniquement qu’un message ne peut pas être écouté. Il est donc impératif pour le commerçant d’utiliser le paramètre de réponse MAC, basé sur le même algorithme de saisie MAC (seuls les paramètres de données seront différents).

Le schéma de données suivant s’applique ici pour la génération du code Hash :   

PayID*TransID*MerchantID*Status*Code

Le paramètre MAC est uniquement retourné à l’URL Success (Réussite) ou Failure (Échec), et Notify (Notification).

Notification de la boutique

Après l’exécution du paiement, la plateforme solution de paiement notifie la boutique du résultat du paiement. Pour ce faire, la plateforme solution de paiement appelle URLNotify via HTTP POST. Il s’agit d’une communication entièrement distincte de la connexion d’origine entre la boutique, l’acheteur et la plateforme solution de paiement. Les paramètres sont transmis dans le corps HTTP en tant que chaîne de paramètre en chiffrement Blowfish. Type de contenu : application/x-www-form-urlencoded; charset=iso-8859-1. Par conséquent, les valeurs standards pour l’analyse du formulaire HTML sont utilisées.

Remarque : l’appel Notify  est autorisé uniquement via le Port 443 (TLS) pour des raisons de sécurité.

Si l’URLNotify de la boutique n’est pas accessible (p. ex. statut HTTP 500/404), la notification est répétée 8 fois. Dans ce cas, le commerçant devra se référer au statut de la demande de transaction (URLSuccess, URLFailure).

Durée avant répétition de la notification calculée après l’échec de la première tentative

Remarque : les paramètres avec encodage URL sont transmis dans des key value pairs (Key1=Value1&Key2=Value2). De nouveaux paramètres peuvent être ajoutés à tout moment, sans préavis. Par conséquent, nous recommandons l’utilisation du nom du paramètre pour l’analyse, et non de l’ordre (la commande) car celui-ci peut changer à tout moment. N’utilisez pas des caractères sensibles à la casse pour ces paramètres, car cela peut être modifié à tout moment. Nous recommandons par exemple de passer tous les caractères en minuscules, et de poursuivre avec des minuscules.

Pour en savoir plus, rendez-vous sur : www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2.1

Redirection du client vers le site web du commerçant

Lorsque le paiement est effectué, le client est redirigé via HTTP GET vers la boutique. La plateforme solution de paiement retourne ensuite un statut HTTP 302 (objet déplacé) et joint le statut du paiement en tant que paramètre avec chiffrement Blowfish à URLSuccess ou URLFailure. Les URLs (Success et Failure) sont des pages spécifiées par le commerçant. Axepta BNP Paribas redirige l’acheteur vers l’une de ces pages en fonction du résultat : URLSuccess si le paiement est réussi et URLFailure si le paiement est échoué.

Tests

Votre compte reste en mode de test jusqu'à ce que la configuration de ce dernier soit terminée : les paiements par carte sont autorisés mais il n'y a pas encore de flux d'argent puisque la plateforme solution de paiement n'exécute pas de captures.

Remarque : en mode test, veillez à n'utiliser que des petits montants entre 0,11 et 2 euros car les autorisations de carte sont authentiques, même en mode test, et réduisent la limite de votre carte. Si vous utilisez des montants plus importants et que vous atteignez la limite de carte, votre carte ne fonctionnera pas temporairement.

En cas de paiements réussis, la plateforme solution de paiement retourne la valeur zéro dans le paramètre Code. Si un paiement échoue, le paramètre Code est supérieur à zéro et s'explique de plusieurs manières : une date d'expiration incorrecte, une limite de carte dépassée... Vous trouverez une liste complète des codes d'erreur dans le fichier Excel correspondant.

Si vous souhaitez tester les différents cas d'erreur, la plateforme solution de paiement vous permet de simuler les codes d'erreur souhaités. Pour simuler une erreur, transmettez le mot-clé Test dans le paramètre OrderDesc suivi du code d'erreur détaillé à quatre chiffres, par ex. « Test:0110 » pour simuler une carte arrivée à expiration. La plateforme solution de paiement retourne alors le code d'erreur détaillé à quatre chiffres ainsi que les paramètres de réponse correspondants.

Cas de test avec délai d'attente (Timeout)

Un paiement par carte est normalement exécuté en une à deux secondes. Dans certains cas, les paiements peuvent être interrompus en raison de longs délais de traitement dans le réseau bancaire. La plateforme solution de paiement met fin aux paiements par carte après 90 secondes. Si vous souhaitez un délai d'attente plus court, notre équipe Support peut configurer ce délai.

Connexion « Server-to-Server »

Payment Page form & card's data are hosted by the merchant

This option (also called machine to machine) means that the merchant’s own payment page is fully hosted on merchant’s environment and all cards data are also collected on the merchant’s server. 

If you wish to design your own forms for entering the payment data, you can process your transactions in the background via a Server-to-Server connection. In this case your system saves payment details such as card numbers or bank account details and then creates a TLS socket-connection to the payment platform Server in order to process the payment. In this variant your system controls the communication with the payment platform which involves more programming than with the payment platform forms which automatically process the payments for you.

The merchant is required to get full PCI DSS certification (PCI level is heavy).

Image Removed

Notice: When processing payments via a Server-to-Server connection your system must control the communication with the payment platform automatically.

Le formulaire de la page de paiement et les données de paiement sont hébergés par le commerçant (Server-to-Server)

L’option server-to-server (également appelée machine-to-machine) signifie que la page de paiement du commerçant est entièrement hébergée sur son serveur, et toutes les données de paiement y sont collectées également. 

Lorsque le commerçant souhaite concevoir ses propres formulaires pour la saisie des données de paiement, il peut exécuter ses transactions en arrière-plan via une connexion serveur-to-serveur. Dans ce cas, le système du commerçant enregistre les détails du paiement, puis crée une connexion réseau (socket) TLS au serveur de la solution de paiement, et envoie ces données afin d’exécuter le paiement. Dans cette variante, le système du commerçant contrôle la communication avec la solution de paiement (cela implique un développement plus poussé comparé aux formulaires de la solution de paiement qui exécutera automatiquement les paiements pour le commerçant).

Le commerçant doit obtenir une certification PCI DSS complète (niveau PCI le plus élevé).

Image Added

Remarque : Veuillez noter que pour un paiement unique (PayID unique), il n’est pas possible de transmettre des requêtes multiples simultanément, il vaut mieux attendre quelques secondes entre deux requêtes d’un même paiement (PayID).

Execution d’un paiement via une connexion Serveur-to-Serveur

La requête pour un paiement débute avec la combinaison correcte des paramètres, comprenant une clé et une valeur séparées par un signe égal (=). Il s'agit des paires nom-valeur (NVP) :

Tous les paramètres sont assemblés pour former une chaîne de caractères et séparés par le caractère

Process of s Server-to-Server payment

The request for a payment starts with the correct composition of the parameters which consist of a key and a value (Name Value Pairs - NVP format) and which are separated by an “equals sign” (=).

All parameters are assembled in a character string and separated by the character &:

Notice: Since the characters "=" and "&" are used as separating characters, these characters cannot be transmitted as values. All values which you transmit without BlowFish-encryption must be URL-Encoded.

There is only one exemption from this rule: For cards which are registered for Verified/SecureCode/SafeKey/JSecure/ProtectBuy for example the ACSURL is transmitted unencoded.

Remarque : les caractères « = » et « & » étant utilisés en tant que caractères de séparation, ils ne peuvent pas être transmis comme des valeurs. Toutes les valeurs que vous transmettez sans chiffrement Blowfish doivent être encodées au format URL.

Une chaîne de caractères correcte pour la solution de paiement contient trois paramètres de base : MerchantID (Identifiant du commerçant), Len (Longueur) et Data (Données). Les paramètres MerchantID et Len ne sont pas chiffrés. Seul le paramètre Data est chiffré avec la méthode Blowfish A correct parameter character string for the payment platform contains three basic parameters: MerchantID, Len and Data. The parameters MerchantID and Len are unencrypted. Only the Data parameter is Blowfish-encrypted:

The Data parameter contains the sensitive payment details such as amount and currency. The encrypted bytes are Hex-encoded and completed to two characters from the left with a zero. Encryption is via Blowfish ECB and is available to you as source-code and components.

The Len parameter is very important for encryption because it contains the length of the unencrypted character string in the Data parameter. Since the data quantity to be encrypted is increased by a multiple of 8 in the case of the Blowfish encryption, the correct length of the character string must be known for decryption. Otherwise accidental characters emerge at the end of the character string.

Le paramètre Data (Données) comprend les détails de paiement essentiels comme le montant et la devise.

Le paramètre Len (Longueur) est très important pour le chiffrement, car il contient la longueur de la chaîne de caractères non chiffrée dans le paramètre Data. La quantité de données à chiffrer étant multipliée par 8 dans le cas du chiffrement Blowfish, la longueur correcte de la chaîne de caractères doit être connue pour le déchiffrement, sans quoi d’autres caractères non prévus apparaissent à la fin de la chaîne de caractères.

L’exemple ci-dessous illustre une requête de paiement non chiffrée The following example show the development of an unencrypted payment request :

Notice: Please note that a value is to be assigned to each parameter. Do not transmit empty parameters, as this can cause the payment to fail.

La chaîne de caractères représentant la requête chiffrée avec la méthode Blowfish est la suivante When this character string is encrypted with Blowfish, it may look like the following :

In order to make payments via a Server-to-Server connection, open a TLS-Socket connection to the payment platform and transfer the generated character string to the following URLAfin de procéder aux paiements via une connexion server-to-server, ouvrez une connexion réseau (socket) TLS avec la solution de paiement et transférez la chaîne de caractères générée sur l’URL suivante :

As soon as the TLS socket connection is made, a normal HTTP POST, version 1.1 is carried out. In this case the following fields are specified in the HTTP header:

Dès que la connexion réseau (socket) TLS est établie, une requête HTTP POST version 1.1 normale est effectuée. Dans ce cas, les champs suivants sont spécifiés dans l’en-tête HTTP :

Mandatory information within HTTP-header

The HTTP Body contains the parameter character string. Note that the values must be submitted as URL-encoded parameters. The following listing is an example of a card paymentLe corps HTTP (HTTP Body) contient la chaîne de caractères du paramètre. Les valeurs doivent être soumises en tant que paramètres avec encodage URL. L’exemple suivant est un paiement par carte :

Notice: Please note that the maximum length of a payment request is limited to 5120 characters. If you require longer strings please contact BNP Paribas Support.

Remarque : la longueur maximale d’une requête de paiement est limitée à 5120 caractères. Si vous devez utiliser des chaînes plus longues, contactez le Support BNP Paribas.

L’exemple suivant montre une réponse type de la solution de paiement. La solution de paiement écrit les données chiffrées en Blowfish sur le The following example shows a typical payment platform’s response. The payment platform writes the Blowfish-encrypted data into the socket :

The decrypted payment platform’s response within the Data parameter looks like thisLa réponse déchiffrée, de la solution de paiement, dans le paramètre Data (Données) se présente comme suit :

It is a synchronous communication such that the Socket-connection remains open until the payment platform has supplied the answer. If a request is not answered within 120 seconds, the payment platform may issue a timeout error message.

Il s’agit d’une communication synchrone, de façon à ce que la connexion « socket » reste ouverte jusqu’à ce que la solution de paiement ait fourni la réponse. Si une requête n’obtient pas de réponse dans les 120 secondes, la solution de paiement peut émettre un message d’expiration.

Remarque : les paramètres URL-encoded sont transmis dans des paires « key-value » Notice: The URL encoded parameters are transmitted in key-value pairs (Key1=Value1&Key2=Value2). Please note that new parameters can be added unannounced at any time. Therefore, we recommend the use of the parameter name for the analysis, not the order since this can change at any time. Please do not use case sensitive mechanisms for the spelling of the parameters as this can change at any time.De nouveaux paramètres peuvent être ajoutés à tout moment, sans préavis. Par conséquent, nous recommandons l’utilisation du nom du paramètre pour l’analyse, et non de l’ordre car celui-ci peut changer à tout moment. N’utilisez pas des caractères sensibles à la casse (sensitive case) pour les paramètres, car cela peut être modifié à tout moment.

Pour en savoir plus, rendez-vous sur For more information, please check:

www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2.1

Fichiers Batch

Batch Manager allows you to transmit payment transactions as files. This file transfer can be done:

• Manually via the Axepta back-office (Please refer to the Back-office document)
• Automatically via the secure file transfer protocol (sFTP)

Image Removed

In this process you assemble transaction data such as the transaction ID, amount and currency in a batch file that you will later transmit to the payment platform. The payment platform then makes the payments and saves the transaction status in the batch file. After processing, the merchant can access to the batch file with the details on the transaction status via a download.

SFTP access for Batch file transfer must be requested at the BNP Paribas Helpdesk.

Batch files must be correctly structured to enable the payment platform to process them.

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).

Image Added

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 :

Le nom d’un fichier batch via FTP :

Name of the Batch files

The name of a new batch file begins with the letter T to indicate the file was originally transmitted by you. This is followed by the Date of the submission in reverse order: e.g. 20160112. This is followed by the MerchantID issued by BNP Paribas and a three-figure Counter, which starts at 001. If you submit several files on one day, you need to set the counter to 002, 003, 004 etc. The file must end in .DAT.

Notice: Please note that the order of the components depends on whether you as the merchant transmit the batch files manually via BNP Paribas Back Office or automated by FTP or sFTP.

The name of a batch file comprises four components:

The processing of the batch file goes through several phases which are indicated within the file name: The original file sent by the merchant starts with the character T (for Transferred). After processing, the batch file is suffixed with the letter P (for Processed).

If a merchant with the MerchantID “TestMerchant” submits two batch files on 12/01/2016 via Axepta Back Office, these two files are named as follows:

T20160112TestMerchant001.dat
T20160112TestMerchant002.dat

W20160112TestMerchant001.dat

W20160112TestMerchant002.dat

 Notice: After you have transmitted the batch file, the processing of the transactions begins. During this processing the file is prefixed with W (for Waiting). If the T batch file is submitted via FTP/sFTP for processing, the phase must be renamed W after the upload by the merchant system. The processing only starts after this step.

P20160112TestMerchant001.dat

P20160112TestMerchant002.dat

Once all payment transactions have been carried out, the payment platform marks the processed files, which now contain the details of the transaction status, with the initial letter P for processed, which you can access in the batch view of BNP Paribas Back Office via download

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 :

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.

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 :

Transfert FTP de fichiers Batch

La solution de paiement vous permet de transférer des fichiers batch automatiquement

FTP tramsfer of Batch files

The payment platform allows you to transfer batch files automatically via FTP (File Transfer Protocol). To transfer a batch file Pour transférer un fichier batch via FTP/sFTP, proceed as followsprocédez comme suit :

1. Save the transaction data in a formatted batch file
2. Encrypt the batch file
3. Transfer the batch file
4. Change of the phase after the upload (T → W)
5. Retrieve the batch file after processing
6. Check status of transactions

1. Enregistrer les données de transaction dans un fichier batch formaté
2. Chiffrer le fichier batch
3. Transférer le fichier batch
4. Changer de phase après chargement (T ® W)
5. Récupérer le fichier batch après traitement
6. 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

Encryption of the Batch file

For security reasons, batch files must be encrypted before the FTP/sFTP transmission. To guarantee maximum security the payment platform uses asymmetric encryption with PGP (Pretty Good Privacy). Encryption with Le chiffrement avec GPG (GNU Privacy Guard) is also possible. The saved file must, however, have the extension “.PGP”, otherwise no processing is possible.

The recognized high security of PGP-encryption is based on a process with two keys, a private key and a public key. BNP Paribas provides you with a public key for encryption of your batch file. The encrypted batch file can then be decrypted only with BNP Paribas's secret private key.

You can also generate public and a private key for your company. The payment platform encrypts the processed batch file with your public key. The file can then be read only with your secret private key.

Format of Batch files

The content of a batch file consists of a header, several records and a footer. Each entry in the file is one row which is completed with CRLF (Enter key). The values within a line are comma-separated. The format is thus also described as the CSV format (Comma Separated Values).

The following sections describe the format of the batch file which you transmit to the payment platform and the response-file, in which the payment platform saves the results of the payments.

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

Format of submitted Batch files

The example below shows the components which make up the content of a batch file.

Notice: Please note that the batch file may not include any empty rows either at the start or the end of the file. The empty rows in the listings are for ease of reading only.

Notice: Please note that text parameters like "Reason" or "OrderDesc" may not contain commas.

Notice: In Batch versions 2.x there is another field for <MID>. Thereby it is possible for a MasterMID to submit transactions for SubMID.

Header

RecordEnregistrement

FooterPied de page

The following example is a batch file for the capture of three card transactions to the value of 1.00 and 2.00 euros. For the first payment the merchant system supplies the reference number 123456 but no reference numbers are supplied for the second and third:

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 :

The description of the individual fields and values used within the data set (Record) within the batch file you will find in the respective chapter within the manual of the individual payment method.

The general parameters for transfer within Header and Footer explain the following table:

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 :

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)

Format of Batch response files

During the processing of the transactions the Batch Manager saves the transaction status to the batch file. To this end two fields, Status and Code, are added to the transaction entries in the Record area:

Record

Notice: When using the authorization renewal, the Batch-response file can include more rows than you have submitted because the payment platform reports failed authorization renewals as Renewal or AuthSplit with the status FAILED. In this case you need to contact the customer.

Notice: The return of optional parameters in the response file generally occurs only if these were included in the submitted file. Generally, no shipment information is given in the response file. If you need this data again, please read this data from the corresponding Notify.

The particular response parameters which Batch manager stores in the record section for each transaction you will find in the batch chapter for the respective payment method.

Batch error codes

From Version 3.0, the payment platform supports detailed error codes. These are eight-digit, hexadecimal codes. The structure and the meaning of the Error codes are described here on the basis of the following example:

The first digit describes the degree of severity of the error. All values greater than 0 indicate warnings or errors.

Notice: An error code doesn’t necessary mean that the payment platform or the merchant system has suffered a technical error. The payment platform also generates an error code if a transaction has failed because the bank regular refuses a payment.

The 2nd to 4th digits of the error code describe the error category. The error categories relate to encryption (001) and format errors (010) and the details of payment methods, initiated in the case of cards (100) through direct debits (110) to Cash&Go (140).

The 5th to 8th digits of the error code give an indication of the error details. Details include instructions on configuration problems such as missing TerminalIDs (0047) and failures at the card holder's bank computing centre (121) but also standard refusals of card payments based on expired cards (110) or declined messages (0100).

Notice: Error-free transactions, for reasons compatibility with Version 2.1, are not characterized by eight but by a zero 0.

You can find a full list of the payment platform’s error codes in a separated excel-file provided to you.

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 :

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 2^e, 3^e et 4^e 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 :

Batch calls and answers

This section describes the parameters which must be transferred within the data set (Record) for executing a card payment and which information can be found within the response file about the payment status.

The structure for a card payment within a Batch file to be submitted is the following:

Example for Exemple de versions batch versions :

The following table describes the individual fields and values used within the data set (record) in the batch file:

Le tableau suivant décrit les champs et valeurs utilisés dans le jeu de données (Record (enregistrement)) dans le fichier batch :

La zone d’enregistrement dans le fichier de réponse pour les transactions par batch se présente comme suit The record area within the response file for Batch transactions looks as follows:

The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):

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) :

In-App (Mobile SDK)

SDK Integration process

For the merchants who already have their own mobile app, we can provide a mobile SDK. An SDK is a collection of software used for developing applications for a specific device or operating system. SDKs typically include an integrated development environment (IDE), which serves as the central programming interface. The IDE may include a programming window for writing source code, a debugger for fixing program errors, and a visual editor, which allows developers to create and edit the program's graphical user interface (GUI).

Our Mobile SDK allows easy and fast integration into the payment platform. The merchant just needs to pass necessary parameters to SDK and SDK handles the entire logic for authentication, validation, message generation, encryption, transfer of the data to the payment platform.

Image Removed

The Mobile SDK is built for native platforms: iOS (iOS 8 as minimum deployment target) and Android (minimum version is 15 (4.0.3)) but is also using “WebView”.

In WebView, the HTML, CSS and JavaScript code base runs in an internal browser (called WebView) that is wrapped in a native app.

The process flow chart is the following:

Image Removed

This communication is based on a one-off token that is exchanged between the 3 actors. 

Image Removed

Payment methods

The mobile SDK is only available for specific payment methods:

Payment method

iOS SDK

Android SDK

Card

PayPal

SEPA Direct Debit

Apple Pay

WeChat Pay

• Cards

SDK is creating request to our existing interface: payssl.aspx. As a result, the card form is displayed in mobile optimized WebView, where customer can type in card details.

All possible card’s features and functionalities are depending on the acquirer and merchant setup.

• PayPal

SDK is creating a request to our existing interface: paypal.aspx. As a result, the customer is re-directed to PayPal mobile optimized WebView, where customer can log in.

Processus d’integration d’une SDK mobile

Pour le commerçant qui possède sa propre application mobile, nous fournissons un SDK mobile, c’est-à-dire un kit de développement logiciel qui contient tous les outils de programmation et les bibliothèques nécessaires à une connexion rapide et fluide de l’application du commerçant à notre solution de paiement. L’intégration des méthodes de paiement à l’application se fait via une interface sans aucun effort de développement de la part du commerçant.

Le développeur n’aura qu’à saisir les valeurs des paramètres adéquates au SDK et c’est au SDK de gérer l’authentification, la vérification, le chiffrement et le transfert des données vers la solution de paiement. C’est aussi au SDK de gérer les réponses de la solution de paiement.

Image Added

Le SDK mobile est construit pour les applications natives développées en iOS (Version 8 au minimum) et Android (Version 15 - 4.0.3 au minimum) mais utilise également des « WebViews ». Ceci dépend du moyen de paiement.

Le processus de paiement est le suivant :

Image Added

Cette communication est basée sur un échange de token entre les 3 acteurs principaux :

Image Added

Moyens de paiement

Le SDK Mobile est valable uniquement pour les moyens de paiement suivants :

Moyen de paiement	SDK iOS	SDK Android
Cartes
PayPal
SEPA Direct Debit
Apple Pay
WeChat Pay

• Cartes

Redirection vers le formulaire de paiement par carte vers l’interface : payssl.aspx (pas de collecte native des données de la carte par le SDK).

• PayPal

Redirection vers la page PayPal pour se connecter : paypal.aspx (en utilisant le contrôleur d'affichage Safari et les onglets personnalisés Chrome).

• SEPA Direct Debit

Redirection vers le formulaire de prélèvement hébergé (pas de collecte native des données IBAN par le SDK) : paysdd.aspx.

• Apple Pay

Apple Pay utilise une API APPLE PAY native.

• WeChat Pay

Le SDK communique avec le WeChat Pay SDK et l’application WeChat app installée dans le smartphone de l’utilisateur. 

Image Added

Distribution SDK

Le SDK est fourni via des injections de dépendances

All possible PayPal features and functionalities are depending on the merchant setup.

• SEPA Direct Debit

SDK is creating request to our existing interface: paysdd.aspx. As a result, the Direct Debit form is displayed in mobile optimized WebView, where customer can type in account details.

• Apple Pay

Apple Pay is using native Apple Pay APIs and elements and is only part of iOS SDK.

• WeChat Pay

Our SDK is enhanced with WeChat Pay SDK, which is then communicating with WeChat app, installed on the user’s mobile phone. 

Image Removed

SDK Distribution

The SDK is provided via Code Dependency Frameworks (Cocoa Pods / GitHub repository).

All necessary information on how to integrate our SDK are available via the following link: Toutes les informations nécessaires sur l’intégration du SDK sont disponibles via ce lien : https://github.com/Computop