Formulaire porteur

Avec la mise en place du 3D Secure V2, il est conseillé de remplir le plus de champs possibles. Le formulaire est considéré comme l'un des plus important. Le scoring de la transaction sera donc bien meilleur, et permettra d'éviter une authentification forte, tout en garantissant le paiement par la banque du porteur.

{
    "lastName": "Janvier",
    "firstName": "Thomas",
    "email": "tjanvier@comnpay.com",
    "phone": "+33606060606",
    "personalPhone": "+33241565858",
    "professionalPhone": "+33707070707",
    "road": "5 Place Albert Durand",
    "road2": "Bâtiment B",
    "road3": "Appartement B315",
    "zipCode": "49100",
    "city": "Angers",
    "country": "France",
    "shipRoad": "11 boulevard Maréchal Foch",
    "shipRoad2": "",
    "shipRoad3": "",
    "shipZipCode": "49100",
    "shipCity": "Angers",
    "shipCountry": "France",
    "customerRef": "numRef001"
}

• Ce formulaire doit être envoyé au format JSON, puis encodé en base 64
• customerRef est utilisé uniquement pour le paiement en 1 clic
• Nous vous conseillons de renseigner les numéros de téléphone au format international. Cela vous sera utile notamment pour le paiement par prélèvement SEPA. Le numéro de téléphone sera alors déjà pré-rempli

Information compte porteur

Avec la mise en place du 3D Secure V2, il est conseillé de remplir le plus de champs possibles.

{
    "chAccDate": "20200130",
    "chAccChange": "20200215",
    "chAccPwChange": "20201001",
    "shipAddressUsage": "20200216",
    "txnActivityDay": 0,
    "txnActivityYear": 12,
    "provisionAttemptsDay": 1,
    "nbPurchaseAccount": 4,
    "suspiciousAccActivity": "01",
    "shipNameIndicator": "01",
}

• Ce formulaire doit être envoyé au format JSON, puis encodé en base 64
• txnActivityDay : Nombre de transactions (réussies et abandonnées) pour ce compte du titulaire de la carte au cours des 24 heures précédentes
• txnActivityYear : Nombre de transactions (réussies et abandonnées) pour ce compte du titulaire de la carte au cours de l'année passée
• provisionAttemptsDay : Tentatives d'ajout de cartes sur ce compte du titulaire
• nbPurchaseAccount : Nombre d'achat (transactions réussies) au court des 6 derniers mois

• suspiciousAccActivity :

  • "01" : Pas d'activité suspicieuse
  • "02" : Une activité suspicieuse a été observée

• shipNameIndicator :

  • "01" : Le nom du compte est similaire au nom de livraison
  • "02" : Le nom du compte est différent du nom de livraison

Panier

Avec la mise en place du 3D Secure V2, il est fortement conseillé de remplir le plus de champs possibles.

{
    "shipIndicator": "01",
    "deliveryTimeframe": "01",
    "deliveryEmailAddress": "tjanvier@comnpay.com",
    "reorderItemsInd": "01",
    "preOrderPurchaseInd": "01",
    "preOrderDate": "20220520",
    "giftCardAmount": 12,
    "nbGiftCard": 1,
}

• Ce formulaire doit être envoyé au format JSON, puis encodé en base 64

• shipIndicator : Mode d'expédition choisi pour la transaction

  • "01" : Envoi à l'adresse de facturation du titulaire de la carte
  • "02" : Envoi à une autre adresse vérifiée par le commerçant
  • "03" : Envoi à une adresse différente de l'adresse de facturation du titulaire de la carte
  • "04" : "Clic and collect" : Enlèvement dans un magasin local
  • "05" : Biens numériques (comprend les services en ligne, les cartes cadeaux électroniques, ...)
  • "06" : Billets de voyage et d'événements, non expédiés
  • "07" : Autres (par exemple, jeux, services numériques non livrés, abonnements à des médias électroniques, etc.)

• deliveryTimeframe : Délai de livraison

  • "01" : Livraison électronique
  • "02" : Expédition le jour même
  • "03" : Expédition de nuit
  • "04" : Expédition en deux jours ou plus

• reorderItemsInd : Indicateur Recommande

  • "01" : Première commande
  • "02" : Recommande d'un même panier

• preOrderPurchaseInd : Indicateur Précommande

  • "01" : Marchandise disponible
  • "02" : Bientôt disponible

• giftCardAmount : Pour un achat de carte prépayée ou de carte cadeau, le montant total de l'achat de la ou des cartes prépayées ou de la ou des cartes cadeaux sans les centimes (par exemple, 12,45 € est 12)
• nbGiftCard : Pour l'achat de cartes prépayées ou de cartes-cadeaux, le nombre total des cartes prépayées ou des cartes-cadeaux/codes achetés. Le champ est limité à 2 caractères

Fonctionnement du champ sec

la valeur de sec est le résultat d'un algorithme qui permet d'être certain que les valeurs reçues par notre système d'information sont bien authentiques et n'ont pas été modifiées par un tiers.

Le fonctionnement est relativement simple :

<?php
  /* Variable contenant l'intégralité des champs de votre formulaire. (bien évidemment la clé secrète n'est pas présente.) */
  $array_tpe

  /* On ajoute la clé secrète aux valeurs. La clé secrète nous sert uniquement à signer la liste des valeurs. */
  $array_tpe['key'] = "CLE SECRETE"

  /* Transformation du tableau de paramètres en une chaine de caractères. */
  $strWithKey = base64_encode(implode("|", $array_tpe))

  /* On retire la clé secrète */
  unset($array_tpe['key'])

  /* On calcul un hash SHA512 de la chaine de caractères représentant les valeurs de votre tableau. Ce hash est la signature unique de votre formulaire HTML, si un tiers modifie les valeurs HTML de votre formulaire sans recalculer la clé SEC notre système refusera la transaction.
  */
  $array_tpe['sec'] = hash("sha512",$strWithKey)
?>

La clé secrète ne doit JAMAIS être présente dans le formulaire html, en effet c'est cette clé qui permet de garantir qu'aucun tiers n'a modifié les valeurs, si vous avez un doute sur la non communication de la clé contactez nous immédiatement.

Types de transactions

Le champ transactionType accepte les valeurs suivantes :

• D : débit immédiat sur la carte du client.
• PA : Pré-autorisation, le paiement ne sera prélevé sur la carte du client qu'après validation de votre part (via les API ou sur l'interface AfonePaiement).
• P3F : Paiement en 3 fois. Un dossier PNF est alors créé pour le client, et un échéancier lui est affiché sur la page de paiement.
• ALS : Création d'alias. Permet la création d'une empreinte de carte (alias), sans débit du porteur. NB : Une demande d'autorisation d'1€ sera effectuée pour valider l'ensemble des informations de carte (non télécollectée)
• SUBD : Abonnement par carte bancaire. Ce type de transaction permet d'effectuer un abonnement totalement configurable (Voir la partie abonnement).
• SUBS : Abonnement par prélèvement. Ce type de transaction permet d'effectuer un abonnement totalement configurable (Voir la partie abonnement).
• SDD : SEPA Direct Debit, prélèvement SEPA sur mandat ponctuel (one off)
• SDDR : SEPA Direct Debit, prélèvement SEPA sur mandat récurrent
• PISCT : Initiation de virement
• PISICT : Initiation de virement instantané

Paiement en 1-clic

Le paiement en 1-clic permet à un client de régler une commande sans saisir de nouveau les informations relatives à sa carte à chaque paiement.

Comme les géants du E-Commerce (Amazon, Cdiscout, Apple, ...), permettez à vos clients d'enregistrer leur carte de paiement !

Cette option devient de plus en plus demandée par les clients, qui recherchent de plus en plus la facilité et la rapidité dans le paiement en ligne. Facile et rapide à mettre en place, cela peut être un vrai plus pour votre boutique.

Voici un exemple réel d'utilisation :

Lors d'un premier paiement, on propose au client d'enregister sa carte pour les prochains paiements :

Si le client mémorise une ou plusieurs cartes, il pourra ensuite en sélectionner une pour effectuer un paiement direct :

L'activation du paiement en 1 clic peut se faire en mode PSP via l'ajout d'un paramètre supplémentaire : customerRef. Ce paramètre unique à chaque client devra nous être envoyé dans le formulaire porteur avant la redirection sur la page de paiement.

Pour rappel, le formulaire porteur permet de fournir des informations clients (nom, prénom, email, adresse, ...) pouvant être utiles lors d'une recherche de transaction. Ce dernier contenant le paramètre du paiement en 1 clic (customerRef) devra être au format JSON puis encodé en base 64

Exemple d'un formulaire porteur :

{
    "lastName": "Janvier",
    "firstName": "Thomas",
    "email": "tjanvier@comnpay.com",
    "phone": "+33606060606",
    "personalPhone": "+33241565858",
    "professionalPhone": "+33707070707",
    "road": "5 Place Albert Durand",
    "road2": "Bâtiment B",
    "road3": "Appartement B315",
    "zipCode": "49100",
    "city": "Angers",
    "country": "France",
    "shipRoad": "11 boulevard Maréchal Foch",
    "shipRoad2": "",
    "shipRoad3": "",
    "shipZipCode": "49100",
    "shipCity": "Angers",
    "shipCountry": "France",
    "customerRef": "numRef001"
}

Paiement par abonnement

Le paiement par abonnement aussi appelé paiement récurrent permet de collecter des paiements réglés par carte bancaire ou par iban de manière périodique. Il est essentiellement proposé à la souscription à un abonnement d’un bien ou un service tel que l’hébergement internet, l’abonnement téléphonique ou encore l’abonnement à une salle de sport.

Cette modalité de paiement, vous permettra de limiter les risques d’impayés et les retards de paiement mais également de fidéliser votre clientèle. Ainsi, vous augmentez votre rentabilité et facilitez l’expérience client, qui n’aura plus à se soucier du paiement, tout est automatique !

Paramétrez facilement la récurrence d’un paiement et définissez les modalités de paiement selon vos besoins :

• Périodicité de l'échéance (deadlinePeriod) : journalier, hebdomadaire, ou mensuel
• Fréquence de l'échéance (deadlineFrequency) (1, 2, 3, 4, ...) par exemple tous les 2 jours, toutes les 3 semaines, tous les 4 mois, ...
• Jour de l'échéance (deadlineDay) (si c'est semaine choisir le lundi, mardi, mercredi, ...) (si c'est par mois, choisir le premier du mois, le 2 du mois, ...)
• Date de fin de l'abonnement (subscriptionEndDate) : avec possibilité de choisir une date de fin (optionnelle)

Exemple d’une configuration d’un abonnement :

{
    "nextDeadlineDate": "201803270000000",
    "deadlinePeriod": "S",
    "deadlineFrequency": 3,
    "deadlineDay": 5,
    "subscriptionEndDate": "20180623000000"
}

Ce formulaire porteur doit être envoyé au format JSON, puis encodé en base 64

L'abonnement sera donc : Tous les 3 Vendredi jusqu'au 23/06/2018 à partir du 27/03/218

Cette nouvelle option est proposée dans le paiement par e-mail, la génération de lien, et est configurable pour la redirection de la page de paiement.

Notez bien que pour l'utilisation de la page de paiement, nous avons créer 2 nouveaux types de transactions : SUBD et SUBS Voir les différents types de transactions

Relance de TNA (transaction non aboutie)

Cette option permet d'inviter un client à retenter le paiement, lorsque que sa tentative initiale a échoué. Grâce à cette option, activable sur votre interface AfonePaiement, votre client reçoit un email (personnalisable) de relance contenant un lien de paiement. Ainsi, vous augmentez votre taux de conversion

D'un point de vue plus technique, il vous faut dans un premier temps renseigner une adresse mail pour l'envoi de la relance. Pour cela, vous devez renseigner le paramètre email dans le paramètre customer. Ensuite, il vous faudra ajouter une référence de commande (arbitrairement choisie par vous) afin de nous indiquer la commande concernée par la relance. Ce paramètre est commandId. Vous trouverez ces deux paramètres dans le détail du formulaire de paiement.

Constructeur

<?php
function __construct($vad_number = "",
                     $secret_key = "",
                     $urlRetourOK = "",
                     $urlRetourNOK = "",
                     $urlIPN = "",
                     $typeTr = "D")
?>

buildSecretHTML

<?php
function buildSecretHTML($produit="Produit",
                         $montant="0.00",
                         $idTransaction="")
?>

Une fois les champs secrets générés vous avez à disposition l'identifiant de transaction généré dans l'attribut "idTransaction" (Exemple : $a->idTransaction;)

validSec

Fonction permettant de valider l'authenticité du message reçu dans votre page IPN

<?php
function validSec($values,
                  $secret_key)
?>

Exemple d'utilisation

Un exemple d'utilisation rapide est présent dans la documentation générale.

Télécharger la librairie

Exemple rapide

Vous trouverez ci-dessous un exemple d'utilisation du PSP dans votre site (appel + réception du résultat de la transaction)

<?php
  include("libs/payment.php");
  $a = new Payment("VAD-XXX-XXX",
                    "secret-key",
                    "http://localhost/retour_ok",
                    "http://localhost/retour_nok",
                    "http://localhost/ipn.php",
                    "D"
                   );
?>
<!doctype html>
<html>
<head>
  <title>Exemple</title>
</head>
<body>
  <form method="post" action="https://secure.comnpay.com">
   <?php echo $a->buildSecretHTML("Produit",10);?>
   <input type="submit" value="Payer!" />
  </form>
</body>
</html>

<?php
  echo "<pre>";
    print_r($_POST);
  echo "</pre>";
?>

IPN

La mise en place de l'option IPN implique que vous devez mettre en place dans votre code une nouvelle page, page qui devra valider la transaction en fonction des données reçues.

L'IPN n'est pas une option obligatoire, cependant si vous souhaitez suivre efficacement vos transactions (et de manière automatique). Nous vous conseillons vivement de l'activer.

Les données de l'IPN possèdent une clé de sécurité `sec` qui vous assure que notre système est bien à l'origine de la requête que vous venez de recevoir.

<?php
  include("libs/payment.php");
  $a = new Payment("VAD-XXX-XXX",
                    "secret-key",
                    "http://localhost/retour_ok.php",
                    "http://localhost/retour_nok.php"
                    "http://localhost/ipn.php",
                    "D"
                   );
?>
<!doctype html>
<html>
<head>
  <title>Exemple</title>
</head>
<body>
  <form method="post" action="https://secure.comnpay.com">
   <?php echo $a->buildSecretHTML("Produit",10);?>
   <input type="submit" value="Payer!" />
  </form>
</body>
</html>

<?php
  include("libs/payment.php");
  if(!validSec($_POST,"secret-key")){
    header('HTTP/1.0 400 Bad Request', true, 400);
    die("ERROR");
  }

  // Affichage des valeurs reçues en POST de l'IPN
  echo "<pre>";
    print_r($_POST);
  echo "</pre>";

  // C'est ici que vous devez effectuer vos traitements, validation de commande, etc...
?>

Le framework Laravel

Laravel est un framework web open-source écrit en PHP respectant le principe modèle-vue-contrôleur et entièrement développé en programmation orientée objet.

ComNpay a créé un exemple qui vous permet d'intégrer facilement et rapidement la solution PSP à votre framework Laravel.

Une documentation technique est disponible pour la mise en place de ComNpay sur Laravel 5 : Voir la documentation

Vous pouvez ainsi télécharger un exemple du module ComNpay :

TELECHARGER