Menu

Intégration Custom - Exemple

1. PREREQUISITES TO OPERATE THE TEST FORM

  • Server configuration  :
    • PHP 7.2 mini
    • PHP Curl activated
    • Dependency Manager  « Composer » installed
    • Configure the site so that all urls are redirected to the index.php file (via an htaccess file [AM1] or a server configuration [AM2])
    • Exemple Apache
      <Directory "/var/www/htdocs">
          RewriteEngine on
          RewriteBase "/var/www/htdocs"
         RewriteCond %{REQUEST_FILENAME} !-f
         RewriteCond %{REQUEST_FILENAME} !-d
         RewriteRule . index.php [L,QSA]
      </Directory>
    • Exemple .htaccess
      RewriteEngine on
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule ^.*$ /index.php [L,QSA]
  • Configuration CENTRALPAY, you need :
    • To hold an API account
    • To authorize the HOST of your form in your Account configuration menu (BO Centralpay)

2. INSTALLATION & CONFIGURATION OF THE FORM

these libraries are necessary for the proper functioning of the 3DS 2.0 test form

  • Configure the form using the “.env” file located at the root of the folder.
    APP_ENV=dev
    HOST_CENTRALPAY_API_CORE='https://test-api.centralpay.net/v2/rest/'
    POS_UUID='change_it'
    API_USER='change_it'
    API_PASSWORD='change_it'
Champ Description
APP_ENV In development, the code always uses the same IP address (8.8.8.8)
In production, use the client's IP address
HOST_CENTRALPAY_API_CORE Centralpay api url: "https://test-api.centralpay.net/v2/rest/" for test mode
POS_UUID Uuid of the point of sale
API_USER API account login
API_PASSWORD API account password

Once the configuration is done, the form can be used.

3. FOLDERS/FILES STRUCTURE

  • "Css" directory: includes the Bootstrap library to manage the layout of the form

  • "JS" directory: includes the jquery, boostrap and jquery.validate libraries to manage javascript calls, form validation, etc.

  • "Templates" directory: contains the files that manage the display of the form

  • "Vendor" directory: contains the libraries downloaded by composer

  • ".env" file: form configuration file

  • "Composer.json" file: Composer configuration file

  • "Index.php" file: file containing all the actions used to manage the form.

 

4. PAYMENT FORM PAGE

When the form is loaded in your browser, the form displays the following :

Several test card numbers are provided :

Numéro de carte Nom de l'action Description
4000001000000091 BROWSER_CHALLENGE Challenge à effectuer pour que le paiement soit accepté
4000001000000067 AUTHENTICATED_BROWSER_FRICTIONLESS Paiement accepté sans avoir à effectuer le challenge
4000001000000075 NOT_AUTHENTICATED_BROWSER_FRICTIONLESS Paiement refusé sans avoir à effectuer le challengee
4000000000000002 Pas dans le range Paiement accepté sans avoir à effectuer le challenge

5. PRINCIPLE OF OPERATION OF THE FORM

All the stages of the form are carried out on a single page (integrated Iframe mode).

In this example, the checks are basic (fields completed, validity of the email address) : there is no check on the data format for example

13DS Versioning

When the customer clicks on the "Submit" button, if the form data is valid, an ajax call is made to the following Centralpay API url: "3ds2/versioning"

Note : Only the card number is sent to the API.

Example of calling the api in the "index.php" file Tag ##API_VERSIONING##

23DS Method

Request made in the backend by the browser to the bank simultaneously with the authentication.

An Iframe calls the url returned by the "3ds2/versioning" API call.

This url corresponds to the element : " threeDSMethodDataForm.threeDSMethodData " returned by the API.

33DS Authentication

Request made in parallel with the 3DS Method.

Another Ajax call is addressed to the following url of the CentralPay API: "3ds2/authentication

Example of call of the api in the file "index.php" Tag ##API_AUTHENTICATION##

The information sent to the API concerns the client's browser :

  • Browser language,
  • Screen size,
  • and so on.

Other values are also returned such as the following fields :

  • threeDSServerTransID : returned by the call to 3ds2/versionning
  • acctNumber : card number
  • deviceChannel : leave 02
  • messageCategory : leave 01
  • purchaseAmount : payment amount in cents
  • purchaseCurrency : currency of the payment
  • threeDSRequestorAuthenticationInd : leave 01
  • notificationURL : notification url after the challenge
  • threeDSRequestorURL : url of the site calling the API

Based on this data, the api will return a transaction status ("transStatus").

  • If Y : the transaction is directly validated,
  • If N : the transaction is automatically rejected,

For all other values, a 'challenge' will be required to validate the transaction.

If the client needs to perform a challenge, an Iframe submits a form to the url returned by the API when calling "3ds2/authentication".

This url corresponds to the value : acsURL

The only parameter sent is : crep which includes the value base64EncodedChallengeRequest

At the end of the challenge, the configured url (parameter notificationURL ) in the "3ds2/authentication" call is called.

43DS Challenge

The information about the challenge is available in the variable cres which is accessible with the POST method. This variable is a JSON data encoded in base 64.

 To decode this value, the following functions can be used :

$retour = json_decode(base64_decode($_POST['cres']), true)

If the value of the variable $retour['threeDSServerTransID'] is equal to Y or A then the client has completed the challenge correctly.

It is then necessary to call the following API url :
" 3ds2/results/'.$retour['threeDSServerTransID']”

Example of calling the api in the file « index.php » Tag ##API_3DS2_RESULTS##

This call will return all the information about the WBS made by the customer. This information will be needed to finalise the transaction.

To finalise this you need to call the API transaction object :

Example of calling the api in the file « index.php » Tag ##API_TRANSACTION##

 

Available parameters :

Nom du champ Description
currency Currency of payment
amount Amount in cents
endUserIp Customer IP address
merchantTransactionId Merchant transaction reference
pointOfSaleId Uuid of the point of sale
browserUserAgent Browser user agent
browserAcceptLanguage Browser language
card[number] Bank card number
card[cvc] Cvc of the bank card
card[expirationMonth] Month of expiry of the bank card
card[expirationYear] Year of expiry of the bank card
card[holderName] Name of the cardholder
order[cardholderEmail] Customer email
card[holderEmail] Customer email
order[firstName] Customer's first name
order[email] Customer email
3ds[xid] Unique identifier of the 3ds auto generated by the merchant site
3ds[cavv] AuthenticationValue received from the 3ds2/result call
3ds[eci] Eci is received from the 3ds2/result call
3ds[status] TransStatus received from the 3ds2/result call
3ds[threeDSServerTransID] The ID of the 3DS server received from the 3ds2/result call

If the http return code of the transaction is equal to 200, then the transaction is valid.

ANNEX A: DIAGRAM

ANNEX B: SAMPLE FORM

Formulaire de paiement

Payment form

Challenge

Challenge

  • 1234 returns Y for successful Challenge
  • 4444 returns A for successful Challenge
  • 1111 returns N for Challenge failed
  • 2222 returns R for Challenge failed
  • 3333 returns U for Challenge failed