Contents
Hosted Payment Page
The Hosted Payment Page (HPP) acts like a proxy allowing the customer to choose between the paymethods offered by your shop.
Credit card payments are then forwarded to the Credit Card Payment Form (PaySSL).
Other paymethods (e.g. PayPal) are formwared to other dedicated payment forms.
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
You will fin all technical inputs in the section Platform Integration for developers
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.
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.
Parameter | Format | CND | Description | ||||
|---|---|---|---|---|---|---|---|
ans..30 | M | MerchantID, assigned by Axepta. Additionally this parameter has to be passed in plain language too. | |||||
ans..5 | M | Message version. Values accepted
| |||||
ans..64 | M | TransactionID which should be unique for each payment | |||||
an12 | M recommended | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional BNP settlement file (CTSF) we cannot add the additional payment data. Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
The format depends on the available paymethods for your MerchantId and this parameter is used for card payments reconciliation. Please choose your format in that way that all paymethods are covered. We recommend to use the most restrictive format for this parameter (AN12 - M) and create unique RefNr. More details : Data reconciliation : Key Data | |||||
n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). | |||||
a3 | M | Currency, three digits according to ISO 4217 Ex : EUR | |||||
OrderDesc | ans..384 | M | Description of purchased goods, unit prices etc. The format depends on the available paymethods for your MerchantId. Please choose your format in that way that all paymethods are covered. More details : Data reconciliation : Key Data | ||||
ans..32 | O | To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, Axepta Platform will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the Axepta Platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. | |||||
an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm | |||||
ans..1024 | O | If specified at request, Payment platform forwards the parameter with the payment result to the shop | |||||
a3 | O | Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization). Values accepted
| |||||
JSON | O | Object specifying authentication policies and excemption handling strategies | |||||
JSON | O | The account information contains optional information about the customer account with the merchant | |||||
JSON | O | The customer that is getting billed for the goods and / or services. Required for EMV 3DS unless market or regional mandate restricts sending this information. | |||||
JSON | O | The customer that the goods and / or services are sent to. Required if different from billToCustomer. | |||||
JSON | O | Billing address. Required for EMV 3DS (if available) unless market or regional mandate restricts sending this information. | |||||
JSON | O | Shipping address. If different from billingAddress, required for EMV 3DS (if available) unless market or regional mandate restricts sending this information. | |||||
JSON | C | Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable. | |||||
JSON | O | The Merchant Risk Indicator contains optional information about the specific purchase by the customer. If no | |||||
| Plain | ans..50 | O | A value to be set by the merchant to return some information unencrypted, e.g. the MID | ||||
| Custom | ans..1024 | O | The merchant can submit several values separated by | which are returned unencrypted and separated by &. Custom=session=123|id=456 will change in the answer to Session=123&id=456 | ||||
ans..256 | M | A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST). Complete URL which Platform calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead.
| |||||
ans..256 | M | A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST). Complete URL which calls up Platform if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Platform and shop, please use the parameter UserData.
| |||||
ans..256 | M | A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST). Complete URL which calls up Platform if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Platform and shop, please use the parameter UserData.
| |||||
a7 | O | Status response sent by Payment platform to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter. | |||||
| CustomField[n] | ans..50 | O | Field that can be used individually by the merchant. Presently 14 fields from CustomField1 to CustomField14 are supported. Please refers to Customize checkout experience |
Common notes: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 Axepta Credit Card Form (payssl.aspx).
Step by step : Create a 20 euros payment
This example is based on the test shop BNP_DEMO_AXEPTA, only credit card payments are setup on this shop.
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*2000*EUR
- HMAC value → 529c65ce765e684d42a29ca255ad99ae40b78715abc8ee958bfdbafd2597d30a
For a Payment request, the PayID (unique ID generated by Axepta) is not know yet, so the first data should be left empty.
So the HMAC will start with *.
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 :
MerchantID=value&MsgVer=value&TransID=value&RefNr&Amount=value&Currency=value&URLNotify=value&URLSuccess=value&URLFailure=value&MAC=value&OrderDesc=value |
Example with BNP_DEMO_AXEPTA
- Required parameters with the values
- MerchantID=BNP_DEMO_AXEPTA&MsgVer=2.0&TransID=1&RefNr=0000000AB123&Amount=2000&Currency=EUR&URLNotify=https://axepta.bnpparibas/&URLSuccess=https://axepta.bnpparibas/&URLFailure=https://group.bnpparibas&MAC=529c65ce765e684d42a29ca255ad99ae40b78715abc8ee958bfdbafd2597d30a&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
- MerchantID=BNP_DEMO_AXEPTA&MsgVer=2.0&TransID=1&RefNr=0000000AB123&Amount=2000&Currency=EUR&URLNotify=https://axepta.bnpparibas/&URLSuccess=https://axepta.bnpparibas/&URLFailure=https://group.bnpparibas&MAC=529c65ce765e684d42a29ca255ad99ae40b78715abc8ee958bfdbafd2597d30a&OrderDesc=Test:0000
- Encryption with the BNP_DEMO_AXEPTA blowfish key
DATA = 43ad07f58ff6a5f9ebbdd42e361d2c85ce4ad41fcd63c697c9ca59076fb5cb782237a2e862a97bb24d949911bb701d698dfed6901f1bcb92404f53b8f5336525167ac5b8a9b89c5fb88d79967366e99e59d95f3f3f0c37126a52495115e28f938e76748a5dc703f7ccbda6ccb4fc253b255c06e0df990fdd94f4313ec2b94142f9978adb9d1079a36a9dbb83e9638e3e58a124d532ece1b7bc175fa340bd0c73c33d4f78374420091e90735bb014a5163d86bfe38795decacf0358075a85c0fbf80c5535046e7f8df64d204c7a4755e07700d4d17c9ef0bdc6e8bbd9c377e3ee0493a0ad2d3a9a624d693d04fe0bdfb3ebb2ef5badb63291ab8d7ad29b4f19b2b0f87dbc0bdb38f282816fe694ac2d512ba741d76a830b2083232246763aa006472661aeb2acf126
LEN = 291
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 :
MerchantID=YourMerchantID&Len=67&Data=0A67FE96a65d384350F50FF1 |
They are added to the Hosted Payment Page endpoint to create the GET request
https://paymentpage.axepta.bnpparibas/paymentpage.aspx?MerchantID=YourMerchantID&Len=67&Data=0A67FE96a65d384350F50FF1 |
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
For additionnal technical information, please refers to Programming basics : Technical implementation and Create an API call and samples to play
Payment methods available
Payment method |
|---|
Cards (CB, Visa, MasterCard, Maestro, JCB, Diners, CUP) |
Direct Debit |
PayPal |
iDEAL (PPRO) |
| Instanea |
Sofort |
giropay |
| Boleto |
paydirekt |
Alipay |
Bancontact |
eNETS |
Finland Online Bank Transfer |
Multibanco |
My Bank |
MyClear FPX |
Przelewy 24 |
POLi |
PostFinance |
paysafecard |
RHB Bank |
TrustPay |
Customize the checkout experience
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) :
Checkout 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 Axepta Credit Card Form (payssl.aspx)
Cusomization capabilities are described in the following page : Customize checkout experience - old - to keep
Details for this page
provides automatic card type detection via card number
your logo can be shown
detailed order and customer information is displayed
How to:
- Your logo:
CustomField3=<Logo-URL> - Order and customer details:
CustomField1..9
Payment page highlighting cards payment
This page is enriched with a drop-down menu showing alternative payment methods (PayPal, iDEAL, Sofort, Wechat…) for a merchant who wants to highlight card payments but also offers other payment methods.
As this page offers many payment methods at the same time, proceeding to payment should be done using the following URL:
Customer experience / flow
- When the user chooses to pay by card, he will be automatically redirected to the specific URL for Axepta Credit Card Form (payssl.aspx)
- When the user chooses to pay with another payment method from the drop-down list, he will be redirected to the specific URL (Please refer to the manual of each available payment method).
To activate this display, the merchant must contact the BNP Paribas Helpdesk:
- Phone : 0 800 25 62 25
- Mail : bnpparibas@computop.com
Cusomization capabilities are described in the following page : Customize checkout experience
Details for this page
provides automatic card type detection via card number
allows selection of other paymethods
your logo can be shown
detailed order and customer information is displayed
How to:
- Your logo:
CustomField3=<Logo-URL> - Order and customer details:
CustomField1..9
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)
Other customization available
Please refers to Customize checkout experience in order to review the several implementations offered by Axepta.