Menu

Intégration Custom - Exemple

1. PREREQUIS POUR FAIRE FONCTIONNER LE FORMULAIRE DE TEST

  • Configuration du serveur :
    • PHP 7.2 mini
    • PHP Curl activé
    • Gestionnaire de dépendance « Composer » installé sur le serveur
    • Configurer le site pour que toutes les url soient redirigées vers le fichier index.php (via un fichier htaccess [AM1] ou une configuration serveur[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 :
    • Détenir des identifiants de compte permettant les appels vers l’API Centralpay
    • Autoriser le HOST du formulaire dans le menu configuration Compte (BO Centralpay)

2. INSTALLATION ET CONFIGURATION DU FORMULAIRE

Champ Description
APP_ENV En développement, le code utilise toujours la même adresse IP (8.8.8.8)
En production, utiliser l’adresse IP du client
HOST_CENTRALPAY_API_CORE Url de l’api Centralpay : 'https://test-api.centralpay.net/v2/rest/’ pour le mode test
POS_UUID Uuid du point de vente
API_USER Login de compte API
API_PASSWORD Password de compte API

Une fois la configuration effectuée, le formulaire est utilisable.

3. ARBORESCENCE DOSSIERS/FICHIERS

  • Répertoire « css » : comprend la librairie Bootstrap pour gérer la mise en page du formulaire
  • Répertoire « js » : comprend les librairies jquery,boostrap et jquery.validate pour gérer les appels javascripts, validation du formulaire, etc..
  • Répertoire « templates » : contient les fichiers gérants l’affichage du formulaire
  • Répertoire « vendor » : contient les librairies télécharger par composer
  • Fichier « .env » : fichier de configuration du formulaire
  • Fichier « composer.json » : fichier de configuration de Composer
  • Fichier index.php : fichier comprenant l’ensemble des actions permettant de gérer le formulaire.

4. PAGE FORMULAIRE DE PAIEMENT

Au chargement du formulaire dans votre navigateur, la formulaire affiche les éléments suivants :

Plusieurs numéros de carte de test sont fournis :

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. PRINCIPE DE FONCTIONNEMENT DU FORMULAIRE

Toutes les étapes du formulaire se réalisent sur une seule et même page (mode Iframe intégrée). Pas de redirection vers une page bancaire ou autre.

Dans cet exemple, les vérifications sont basiques (champs complétés, validité de l’adresse email) : il n’y a pas de vérification sur le format des données par exemple

13DS Versioning

Lorsque le client clique sur le bouton « Submit », si les données du formulaire sont valides, un appel ajax est effectué vers l’url suivante de l’API Centralpay : « 3ds2/versioning »

Remarque : seul le numéro de carte est envoyé à l’API.

Exemple d’appel de l’api dans le fichier « index.php » Tag ##API_VERSIONING##

23DS Method

Requête réalisée en backend par le navigateur vers la banque simultanément avec l’authentification.

Une Iframe appelle l’url retournée par l’appel de l’API « 3ds2/versioning ».

Cette url correspond à l’élément : « threeDSMethodDataForm.threeDSMethodData » retourné par l’API.

33DS Authentication

Requête réalisée en parallèle simultanément avec le 3DS Method.

Un autre appel Ajax est adressé vers l’url suivante de l’API CentralPay : « 3ds2/authentication »

Exemple d’appel de l’api dans le fichier « index.php » Tag ##API_AUTHENTICATION##

Les informations adressées à l’API concernent le navigateur du client :

  • Langue du navigateur,
  • Dimensions de l’écran,
  • etc.

D’autres valeurs sont également retournées tels que les champs suivants :

  • threeDSServerTransID : retourné par l’appel à 3ds2/versionning
  • acctNumber : numéro de carte
  • deviceChannel : laisser 02
  • messageCategory : laisser 01
  • purchaseAmount : montant du paiement en centimes
  • purchaseCurrency : devise du paiement
  • threeDSRequestorAuthenticationInd : laisser 01
  • notificationURL : url de notification après le challenge
  • threeDSRequestorURL : url du site appelant l’API

En fonction de ces données, l’api va retourner un statut de transaction (« transStatut »).

  • Si Y : la transaction est directement validée,
  • Si N : la transaction est automatiquement refusée,
  • Pour toutes autres valeurs, il sera nécessaire d’effectuer un ‘challenge’ pour valider la transaction.

Si le client doit effectuer un challenge, une Iframe soumet un formulaire à l’url retournée par l’API lors de l’appel à « 3ds2/authentication ».

Cette url correspond à la valeur : acsURL

Le seul paramètre envoyé est : creq qui comprend la valeur base64EncodedChallengeRequest

A la fin du challenge, l’url configurée (paramètre notificationURL ) dans l’appel « 3ds2/authentication » est appelée.

43DS Challenge

Les informations concernant la challenge sont disponibles dans la variable cres qui est accessible avec le méthode POST. C’est variable est une donnée JSON encodée en base 64.

 Pour décoder cette valeur il suffit d’utiliser les fonctions suivantes :

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

Si au retour du challenge le statut de transaction (transStatus) est égal à Y ou A alors le client a effectué le challenge correctement et le paiement est accepté.

Si le statut de transaction est égal à une autre valeur alors le client n'a pas effectué le challenge correctement et le paiement est refusé.

Il est alors nécessaire d’appeler l’url suivante de l’API :
« 3ds2/results/'.$retour['threeDSServerTransID']”

Exemple d’appel de l’api dans le fichier « index.php » Tag ##API_3DS2_RESULTS##

Cet appel nous retournera toutes les informations concernant l’OTP réalisé par le client. Ces informations seront nécessaires pour finaliser la transaction.

Pour finaliser celle-ci il faut appeler l’objet transaction de l’API :

Exemple d’appel de l’api dans le fichier « index.php » Tag ##API_TRANSACTION##

 

Paramètres disponibles :

Nom du champ Description
currency Devise du paiement
amount Montant en centimes
endUserIp Adresse IP du client
merchantTransactionId Référence de la transaction du marchand
pointOfSaleId Uuid du point de vente
browserUserAgent User agent du navigateur
browserAcceptLanguage Langue du navigateur
card[number] Numéro de la carte bancaire
card[cvc] Cvc de la carte bancaire
card[expirationMonth] Mois d’expiration de la carte bancaire
card[expirationYear] Année d’expiration de la carte bancaire
card[holderName] Nom du porteur de carte
order[cardholderEmail] Email du client
card[holderEmail] Email du client
order[firstName] Prénom du client
order[email] Email du client
3ds[xid] Identifiant unique du 3ds auto généré par le site marchand
3ds[cavv] AuthenticationValue reçu de l’appel 3ds2/result
3ds[eci] Eci reçu de l’appel 3ds2/result
3ds[status] TransStatus reçu de l’appel 3ds2/result
3ds[threeDSServerTransID] L'ID de serveur 3DS,  reçu de l’appel 3ds2/result

 Si le code de retour http de la transaction est égal à 200, alors la transaction est valide.

ANNEXE A : SCHEMA

ANNEXE B : EXEMPLE FORMULAIRE

Formulaire de paiement

Formulaire de paiement

Challenge

Challenge

  • 1234 retourne Y pour Challenge réussi
  • 4444 retourne A pour Challenge réussi
  • 1111 retourne N  pour Challenge échoué
  • 2222 retourne R pour Challenge échoué
  • 3333 retourne U pour Challenge échoué