Contents

Integration

The Hosted Payment Page (HPP) offer the easiest way to integrate AXEPTA :

• Your system just need to request the Payment form from AXEPTA
• the customer enters the payment data into the form which send them to AXEPTA
• the payment is processed by AXEPTA automatically
• and AXEPTA sends a notification to your shop system with the result of that payment process.

You just need to:

• build the API request initiating the payment process
• supply URLs for success, failure, back and notification

AXEPTA handles automatically:

• Validation of customer input data
• Retry of customer input in case of failure
• Handling of 3-D Secure authentication form provided by banks for 3-D Secure 1.x and s-D Secure 2.x
• Automatic handling of soft decline, i.e.: an authorization which requires authentication

How to call the Hosted Payment Page ?

To make payment requests via the payment methods selection page, the merchant should send a request to the following URL with HTTPS GET or HTTPS POST:

All details required for payment processing are forwarded as parameters.

Create a request : 20 euros payment on Hosted Payment Page

Calculate the HMAC value

The HMAC value is obtained by ciphering the string PayID*TransID*MerchantID*Status*Code with the HMAC key of your shop.

Example with BNP_DEMO_AXEPTA

• PayID*TransID*MerchantID*Amount*Currency → *1*BNP_DEMO_AXEPTA*20*EUR
• HMAC value → FCCF8F2BEDC06E7C3C270B0D4DC4CEE9640E4B4A5577763C2E3CDDFC84913D56

Calculate the DATA and Len values

The DATA parameter is obtained by ciphering all the parameters required for the payment with the blowfish key of your shop.

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

At least, a request payment should contain the following parameters

Example with BNP_DEMO_AXEPTA

• Required parameters with the values
  • MerchantID=BNP_DEMO_AXEPTA&MsgVer=2.0&TransID=1&RefNr=0000000AB123&Amount=20&Currency=EUR&URLNotify=https://axepta.bnpparibas/&URLSuccess=https://axepta.bnpparibas/&URLFailure=https://group.bnpparibas&MAC=FCCF8F2BEDC06E7C3C270B0D4DC4CEE9640E4B4A5577763C2E3CDDFC84913D56&OrderDesc=Test:0000
    • If you use BNP_DEMO_AXEPTA you have to use "OrderDesc=Test:0000" but this is not mandatory with your own MID
• Encryption with the BNP_DEMO_AXEPTA blowfish key

  • DATA = 43AD07F58FF6A5F9EBBDD42E361D2C85CE4AD41FCD63C697C9CA59076FB5CB782237A2E862A97BB24D949911BB701D698DFED6901F1BCB92404F53B8F5336525167AC5B8A9B89C5F3D80BA112B99F32627CEA3CC11C6705870841F76DFEC778FC6632D6C88F6D35C58A124D532ECE1B7BC175FA340BD0C73C33D4F7837442009D914600CCA004DF475C31063C5E418325123C7BB6AC2A8BA16DFAB4FA44BAB6183B05F39EE3590B5BE79E5C7B23B2C14386AE7FCD0FD6C58D20FA4502023E24CE1F4882D87F1FC3E367EC88EEEFB052D26756376200D7765ADE87154E8F2AA12B9D057E93BDAF3AF07CDF662A4BE580896060EDD3EB8678245BB6FA2F134676205C5F12BD21820A2ABA0E4B4AC8A33F174B8C83BE2C4E495F53AA564EF053474A5EF33192ADD9A81

  • LEN = 289

Finalize the request

A correct parameter character string for Platform contains three basic parameters: MerchantID, Len and Data.

The parameters MerchantID and Len are unencrypted. Only the Data parameter is Blowfish-encrypted such as :

They are added to the Hosted Payment Page endpoint to create the GET request 

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

Example with BNP_DEMO_AXEPTA

https://paymentpage.axepta.bnpparibas/payssl.aspx?MerchantID=BNP_DEMO_AXEPTA&Len=289&DATA=43AD07F58FF6A5F9EBBDD42E361D2C85CE4AD41FCD63C697C9CA59076FB5CB782237A2E862A97BB24D949911BB701D698DFED6901F1BCB92404F53B8F5336525167AC5B8A9B89C5F3D80BA112B99F32627CEA3CC11C6705870841F76DFEC778FC6632D6C88F6D35C58A124D532ECE1B7BC175FA340BD0C73C33D4F7837442009D914600CCA004DF475C31063C5E418325123C7BB6AC2A8BA16DFAB4FA44BAB6183B05F39EE3590B5BE79E5C7B23B2C14386AE7FCD0FD6C58D20FA4502023E24CE1F4882D87F1FC3E367EC88EEEFB052D26756376200D7765ADE87154E8F2AA12B9D057E93BDAF3AF07CDF662A4BE580896060EDD3EB8678245BB6FA2F134676205C5F12BD21820A2ABA0E4B4AC8A33F174B8C83BE2C4E495F53AA564EF053474A5EF33192ADD9A81

• Calcul du HMAC pour sécuriser le montant et la devise
  • Chaîne de caractère à chiffer avec la clé HMAC : PayID*TransID*MerchantID*Status*Code
  • Certaines valeurs peuvent être laisser vide
• Construire les objets JSON et les encoder en Base64 avec padding
• Assembler les paramètres (clé / valeur, objets JSON) de l'API
• Chiffrer tous les paramètres de l’API avec la clé Blowfish : cela permettra d’obtenir les paramètres Data et Len
• Si besoin, ajouter des paramètres simples pour personnaliser la page de paiement hébergée par (par exemple language="en" pour utiliser la langue anglaise, les customFields)
• Envoyer la demande d’API au endpoint choisi

The request for a Platform form starts with the correct composition of the parameters which consist of a key and a value which are 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 which you transmit without BlowFish-encryption must be URL-Encoded.

A correct parameter character string for 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 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 Axepta Helpdesk.

The following listings show the development of a payment request. The first listing is the unencrypted parameter character string:

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.

This character string is encrypted and transmitted as the Data parameter. The HTTPS GET request for a Platform form for credit card payments looks like this:

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

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.

Example

Language of the payment page

The standard BNP Paribas payment page is available in 7 languages : french, english, german, spanish, portuguese, italian and dutch. 

By default, the language of the payment page will match the language used previously by the user, on the merchant's website. However, the user will have the possibility to change the language once he arrives on the payment page thanks to a scrolling menu, on the top right of the page (see below) :

Payment experiences

There are 3 different options to display the payment methods on the Axepta Online payment page:

• Payment page offering cards only - HPP will call paySSL.aspx
• Payment page highlighting cards payment - HPP will call paySSL.aspx
• Payment page offering all payment methods available on the shop (cards payment and alternative payment methods)

Payment page offering cards only

If the merchants wants to offer payment by cards only (CB, Visa, MasterCard, Amex…), the credit card form (payssl.aspx) can be called directly.

In deed, this page shows card payment checkout only.

To make card payments via the payment platform form, please use the following URL:

The general parameters of a payment request by card are available at Credit Card Form (payssl.aspx)

Payment page offering all payment methods available on the shop (cards payment and alternative payment methods)

This page shows all the logos of the available payment methods, so the merchant is not highlighting any payment method. 

As this page offers many payment methods at the same time, proceeding to payment should be done using the following URL :

The user will be automatically redirected to the specific URL of the chosen payment method (please refer to each payment method guide).

This page is displayed to the merchant by default. If the merchant wants to reorganize the payment methods’ order, he must configure the payment methods in the “PayTypes” parameter according to his preferred order. (More information about this parameter in the Definition of parameters values section)

Checkout experiences and customization

Please refers to Customize checkout experience in order to review the several implementations offered by Axepta.

Request parameters

The following parameters are mandatory for all payment methods and have to be submitted Blowfish-encrypted within the Data parameter to the payment methods selection page.

These parameters are mandatory for all payment means and must be transmitted and Blowfish-encrypted in the “Data” parameter.

Notice: Please take all further parameters specifically for a payment method from the manual of the respective payment method.

Response

When the payment is completed Axepta Platform will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess resepctively to the URLFailure.

The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.

The content of the response depends on the payment method choose by the client.

For credit cards payment, please refers to Credit Card Form (payssl.aspx).

Payment methods available