Contents

Document history

Introduction

The BNP Paribas payment platform (also called Payment Platform or Payment Gateway) offers several interfaces for the submission of payment tasks.

This manual describes the programming of the platform and serves to connect PSP system.

The platform will process the data and carries out payment transactions. Therefore the payment gateway will ensure the secure processing of all transactions.

Chart of process flow via Server-to-Server connection

Server-to-Server integration

Server to server (also called machine to machine): 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. Your system controls the communication with Payment platform which automatically process the payments for you.

The PSP is required to pass full PCI DSS certification.

In the case of payments via the Server-to-Server connection, the PSP holds payment details such as card numbers and bank account details. PSP systems create a TLS socket-connection to the Payment platform server in order to carry out a payment transaction.

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

Process of a Server-to-Server payment

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