Table des matières

Historique des versions

Introduction

La plateforme 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 de paiement Axepta BNP Paribas au système du commerçant et s’adresse aux développeurs et aux responsables techniques.

Principles majeurs de la programmation de la plateforme

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

• Se connecte via Internet à la plateforme 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 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.

Integration de la plateforme de paiement Axepta Online

La plateforme 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 formulaires de la page de paiement et les donnees de paiement sont héberges par Axepta

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

La plateforme 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 de paiement pour le faire apparaitre 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 donnees de paiement sont héberges 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 de paiement doivent être désactivées en utilisant le mode « paynow » car la plateforme 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 de paiement débute avec la composition correcte des paramètres comprenant une clé et une valeur séparés 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 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 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 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 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 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 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 de paiement notifie la boutique du résultat du paiement. Pour ce faire, la plateforme 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 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 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 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 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 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 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 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).

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

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.

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.

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.

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

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:

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

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.

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

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.

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.

For more information, please check:

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

Batch files

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)

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.

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:

 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.

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

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 via FTP/sFTP, proceed as follows:

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

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

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

Record

Footer

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:

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:

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.

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 batch versions :

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

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

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.

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:

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

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.

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. 

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: https://github.com/Computop