Table des matièresContents

Historique des versions

Introduction

La plateforme de paiement Axepta BNP Paribas payment platform will accept payment orders, process the data and carry out the merchant’s payment transactions in a secure way.

This manual describes the programming of the payment platform and serves to connect merchant’s system.

Major principles of the platform programming

In order to send payment orders to the payment platform Axepta BNP Paribas, the merchant:

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

• Connects via Internet to the payment platform.
• Sends the required payment data in a defined homogeneous format.

The payment platform Axepta BNP Paribas eliminates the need for using complex software on the merchant’s server to ensure the compatibility with the different programming languages and the different operating systems (Linux, Unix, Windows). Software installation generally causes problems with operating system versions or security regulations.

Regardless of the payment method, the same parameters are transmitted so that all payment methods operate in the same way and require no additional effort.

The location of payment data storage is very important for the security of the payments online. The card organizations have established a security program with the PCI security authorization (Payment Card Industry) in order to guarantee the secure storage of card data.

, 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

Integration of Axepta Online payment platform

The payment platform offers 4 different integration options:

• Payment via the payment page form
• Payment via server-to-server connection
• Payment via Batch
• Payment via mobile application (Mobile SDK)

Payments via Payment Page forms

Payment Page form & card's data hosted on Axepta BNP Paribas server

This option means that the Payment Page is hosted on BNP Paribas' secure environment. Using this option is the easiest and fastest method to integrate the solution.

The Payment page is displayed to the customer in full redirect, iframe or lightbox (Pop-up).

The payment platform provides HTML-forms with TLS-encryption and SSL-certified. The website only needs to request the “HTML form” from the payment platform to connect the customer to the payment platform to proceed to the payment. Customers then enter payment details in the payment platform HTML form. Data will be transferred via HTTP POST request as URL parameters (URL: payssl.aspx).

The merchant is only required to comply with SAQ-A (Lowest level of PCI DSS).

Image Removed

Payment Page form hosted by merchant & card's data hosted by Axepta

This option (also called « Silent order post » or « Direct post ») means that the merchant's own payment Page is hosted on his server, but the card data is not sent to merchant's server, they are directly POSTed to BNP Paribas' server.

After the customer has entered his card data, the payment data is forwarded to the Silent order post page, where the further payment processing occurs via 3D-Secure. The form details must be directly forwarded to the Silent order post page and may not be transmitted to the merchant’s system. Also, no PCI-relevant data may be transmitted to the Silent order post page as additional input parameters.

The parameters are not forwarded as URL parameters as is the case when calling the payssl.aspx, but as form input parameters.

Merchant is required to comply with SAQ-A EP (PCI level is light).

Image Removed

Notice: Please note, that automatic retry attempts at the payment platform must be deactivated when using the “Paynow.aspx”. The background is that at a retry attempt, the payment platform cannot send back the customer to the previously used special shop form. Please contact the BNP Paribas Support to deactivate the retry attempts.

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.

Image Added

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.

Image Added

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

Request for a BNP Paribas Payment Page form

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

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 that you transmit without BlowFish-encryption must be URL-Encoded.

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 A correct parameter character string for the payment platform contains three basic parameters: MerchantID, Len and Data. The values of the parameters MerchantID and Len are unencrypted. Only the Data parameter is Blowfish-encrypted:

The Data parameter contains the sensitive payment details such as the amount and the 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 parameters are transmitted via HTTPS POST or HTTPS GET. The recommended transmit method is HTTPS POST because the parameter character string in the case of GET is attached to the URL, which is limited to 2048 bytes depending on the browser.

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.

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 :The following example shows 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.

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 This character string is encrypted and transmitted as the Data parameter. The HTTPS GET request for the payment platform’s form for card payments looks like this:

Notice: Please note that the parameters are transmitted unencrypted for the purpose of layout of the form.

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 An HTML form is produced for HTTPS POST and all parameters are transmitted as Hidden Fields. Only the Pay button is visible to the customer:

Authentification Hash MAC

To protect against unauthorized manipulation of your payment transactions, the payment platform checks with the aid of a Hash Message Authentication Code (HMAC) whether your payment enquiry is authentic and has not been manipulated. For this purpose, you transfer an HMAC value to the payment platform with each transaction in the parameter MAC.

Background: Unlike the HMAC procedure, every encoding method has the disadvantage that there is a matching decoding method. Anyone who possesses the correct key or cracks the encryption can read and manipulate the data. Therefore, no encryption method is ever 100% safe. In the case of the Hash procedure, conversely, decoding is impossible, so that a Hash value can confirm the authenticity of the message free of doubt.

The payment platform uses a Hash Message Authentication Code (HMAC) to check the authenticity of your payments. The MAC SHA-256 algorithm is used with a 32-digit key length (256 bits) for this. The additional password makes the HMAC procedure particularly safe.

The following table describes how you can generate the Hash values for your payment:

Step	Task
1	You receive the HMAC via email
2	The HMAC value is calculated with the aid of the password and several parameter values. For the calculation, the parameters PayID, TransID, MerchantID, Amount and Currency are used and separated with asterisks: PayID*TransID*MerchantID*Amount*Currency Notice: If a transaction does not support all of these parameters, you can simply omit the missing value. For example, there is no PayID yet with the first transaction, so you do not have to transfer this. The PayID is a component of the Hash calculation in subsequent transactions: Example 1, without PayID (e.g. when authorising): *B456Ref890*YourMerchantID*9900*EUR   Example 2, with PayID (e.g. when capturing): 1237890*B456Ref890*YourMerchantID*9900*EUR   Example 3, without TransID: 1237890**YourMerchantID*9900*EUR
3	Use the MAC SHA-256 algorithm, which nearly all programming languages support, in order to calculate the Hash value with the password and the parameter values.
4	Use the MAC parameter to transfer the hexadecimal encoded Hash value to the Payment platform with each transaction in the encoded data field.

Notice: Note that the MAC parameter is mandatory for all subsequent transactions (e.g. capture, refund note) if it was transferred with the first transaction (e.g. authorization).

Important: The payment platform rejects transactions with wrong or missing HMAC values promptly without further processing, because this is an indication of hacker attacks. Therefore, transactions which the payment platform rejects with the error codes 20100044 or 20120044 do not appear in BNP Paribas Back Office.

Request without PayID: MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.fr/ok.html&URLFailure=https://www.shop.fr/failed.html&OrderDesc=My purchase String for MAC generation: *100000001*Test*11*EUR Request with MAC: MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.fr/ok.html&URLFailure=https://www.shop.fr/failed.html&OrderDesc=My purchase&MAC=A0E3A8BB9473CF4D3F91181E0859650A9AF3F4AD0AE1E839AC7B750247A2E947 Request without TransID: MerchantID=YourMerchantID&PayID=8ee4e922c39446ac9ee66095a4a4b475&Amount=100&Currency=USD String for MAC generation: 8ee4e922c39446ac9ee66095a4a4b475**Test*100*USD Request with MAC: MerchantID=YourMerchantID&PayID=8ee4e922c39446ac9ee66095a4a4b475&Amount=100&Currency=USD&MAC=F1EB4A8BB9473CF4D3F91181F0859659A9AF3F4AD0AE1E839AC7B750247A2D636

 

The merchant´s website must verify that a notification request really comes from BNP Paribas. Otherwise an attacker can initialize a transaction and then falsify this notification. A shop operator will not manually check whether a corresponding transaction was performed in each case. Therefore, the module must do this automatically.

Currently, the notification request is only encrypted. However, this encryption does not guarantee the authenticity of a message. It only guarantees that a message cannot be listened in on. Therefore, this safety measure is insufficient. As a result, the response parameter MAC is used, which is formed via the same algorithm as the input MAC. Only the data parameters differ.

The following data pattern applies here for hash generation:

PayID*TransID*MerchantID*Status*Code

The MAC parameter is only returned to the Success or Failure URL and for Notifys.

Notification of the shop

After processing the payment, the payment platform notifies the shop of the payment result. To do this, the payment platform calls URLNotify via HTTP POST. This is an entirely separate communication which has nothing to do with the original connection between the shop, the customer and the payment platform. The parameters are transmitted in the HTTP Body as a Blowfish-encrypted parameter string. The content type is application/x-www-form-urlencoded; charset=iso-8859-1. Therefore, the standard values for HTML-form analysis are used.

Notice: Please note that the Notify-call is permitted only via Port 443 (TLS) for security reasons.

If the shop’s URLNotify is not accessible (e.g. HTTP-status 500/404), notification is repeated 8 times. In this case the customer transmits to the shop is prior to the URLNotify request. Therefore, the shop should analyse and compare both status messages from URLNotify and transmission (URLSuccess, URLFailure).

Time of repeat of Notify respectively calculated after first failed attempt

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 example, it is recommended switching all parameters “to lower” and continuing in lower case.

For more details please go to:

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

Transfer of the customer back to the merchant website

Once the payment is complete, the customer is redirected via HTTP GET back to the shop. The payment platform then returns an HTTP Status 302 (object moved) and attaches the payment status as Blowfish-encrypted parameters to URLSuccess or URLFailure. These URLs (Success and Failure) are specific web pages added by the merchant. Axepta BNP Paribas redirects the customers to one of these web pages according to the result of the transaction: URLSuccess if the payment succeeds and URLFailure if the payment fails.

Tests

Until you have completed the programming, your payment platform account is in test mode: card payments are authorized but there is no cashflow because the payment platform has not instigated a capture.

Notice: Please use only small amounts between 0.11 and 2 euros in test mode because the card authorizations are authentic even in the test mode and reduce the limit of your card. If you use large amounts and reach the card limit, your card will no longer work temporarily.

In the case of successful payments, the payment platform returns the value zero in the Code parameter. If a payment fails, the Code parameter is greater than zero, for which there may be many reasons:  an incorrect expiry date, an exceeded card limit or even a blocked card are just a few examples. You can find a full list of error codes in an Excel file (Error codes list).

If you wish to test the different error cases, the payment platform allows you to simulate the desired error codes. To simulate an error, transmit the keyword Test in the OrderDesc parameter followed by the four-digit detailed error code, for example "Test:0110" to simulate an expired card. The payment platform then returns the four-digit detailed error code with the respective response-parameters.

Test case with timeout

A card payment is normally completed within one to two seconds. In a few cases however, payments may be terminated due to long processing times in the banking network. The payment platform terminates card payments after 90 seconds. If you prefer shorter timeouts our Support can configure it.

Payments via « Server-to-Server » connection

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