ComNpay - Développeur

Le PSP

Introduction

La solution via formulaire de paiement (PSP) permet à n'importe qui d'utiliser la puissance de ComNpay dans son site marchand. Il suffit d'utiliser une des librairies présentes dans la documentation pour mettre en place simplement et efficacement une solution de paiement paramétrable et puissante.

./static/img/pspv2.png

Principe

L'installation du PSP dans votre site web se déroule en 3 étapes :

  • Souscription d'un compte sur le site ComNpay. (ou demande de compte sur notre plateforme d'homologation).
  • Récupération de la librairie correspondant au langage de votre site Internet. (Optionnel) (Vous utilisez un CMS ?)
  • Création d'une page qui a pour but de rediriger l'internaute vers le formulaire de paiement (PSP). Celle-ci sera constitué d'un simple FORM html et de champs spécifiques. (Ex: ComNpay en 30 secondes)

Utilisation

Nous essayons de fournir des librairies permettant de simplifier l'utilisation du PSP quelque soit le langage de votre site web, si vous ne trouvez pas le langage qui correspond à votre site n'hésitez pas à nous contacter. Les librairies sont bien évidemment optionnelles, mais nous vous conseillons vivement de les utiliser pour accélérer le temps d'intégration de notre solution.

Elles vous permettront d'appeler simplement le PSP et de valider le retour de celui-ci.

Pour pouvoir utiliser le PSP vous devez dans un premier temps récupérer les informations de connexion présentes dans votre espace protégé sur le site AfonePaiement. Celles-ci sont disponibles dans la section ComNpay puis sous le menu paramétrage.

Attention les identifiants (et surtout la clé secrète) sont strictement personnels. Ils ne doivent en aucun cas être communiqués à un tiers.

ComNpay en 30 secondes

L'exemple suivant indique comment utiliser ComNpay dans votre site web

Exemple PHP mais valide quelque soit le langage

<?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>

IPN? Exemples détaillés? C'est par ici

Intégration manuelle du formulaire de paiement

Si vous ne souhaitez pas intégrer une de nos librairies pour utiliser la solution ComNpay vous allez devoir créer un formulaire HTML avec les champs suivant :

Paramètre Description Exemple
amount Montant de la transaction 10.00
serialNumber Identifiant de votre TPE ComNpay DEMO
transactionId Référence unique de transaction 123456-DEMO-A456456
commandId Référence de commande utilisable dans la relance de transaction non aboutie commande_1_123456-DEMO-A456456
currency Devise de la transaction EUR
lang Langue de la page de paiement fr
productName Nom du produit Mon Produit
urlOK URL de redirection après paiement accepté http://votresite/urlOK.html)
urlNOK URL de redirection après paiement refusé http://votresite/urlNOK.html)
urlIPN   http://votresite/ipn
data Valeur non traitée par ComNpay, simplement renvoyée via l'IPN  
transactionType Type de transaction D : Débit, PA : Pré-autorisation, P3F : Paiement en 3 fois
sec Valeur calculée par votre serveur  
preauthoTitle Personnalisation titre "Information pré-autorisation"  
preauthoMessage Personnalisation message en infobulle dans le cas d'une pré-autorisation  
aliasTitle Personnalisation titre "Identification de votre carte"  
aliasMessage Personnalisation message en infobulle dans le cas d'une identification de carte  
userFieldsMessage Personnalisation message invitant l'utilisateur à indiquer des informations personnelles complémentaires  
customer Fortement conseillé pour la mise en place du 3DS V2  
cardholderAccount Conseillé pour la mise en place du 3DS V2  
caddy Conseillé pour la mise en place du 3DS V2  
subscription Permet la mise en place d'un abonnement (paiement récurrent complet)  
template Code du template de personnalisation de la page de paiement (permet d'avoir plusieurs styles de page de paiement sur un même compte). Si non fourni, le template par défaut sera utilisé  

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 :

./static/img/pspv2-savecard.png

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

./static/img/pspv2-oneclick.png

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.

Les méthodes disponibles dans les librairies

Constructeur

Parametre Détail
vad_number Numéro de série du TPE, information présente dans la partie parametrage de votre compte AfonePaiement
secret_key Clé privée pour vos transactions. Attention ne JAMAIS divulguer cette valeur à un tiers. L'information est présente dans votre compte AfonePaiement
urlRetourOK URL de retour lors de la réussite du paiement. (Doit être accessible depuis l'utilisateur)
urlRetourNOK URL de retour lors de l'échec du paiement. (Doit être accessible depuis l'utilisateur)
urlIPN URL IPN, cette url sera appelée depuis nos services à la fin du processus de paiement.
typeTr Type de transaction, D pour Débit, PA pour Pré-autorisation, ALS pour création d'alias (Par défaut D)
<?php
function __construct($vad_number = "",
                     $secret_key = "",
                     $urlRetourOK = "",
                     $urlRetourNOK = "",
                     $urlIPN = "",
                     $typeTr = "D")
?>

buildSecretHTML

Parametre Détail
produit Nom du produit. Information affichée au client sur le PSP
montant Montant de la transaction. Séparateur des centimes : '.'
idTransaction Optionnel, identifiant de transaction UNIQUE. Si non spécifié un identifiant est généré.
<?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

Parametre Détail
values Les valeurs reçues en POST (variables envoyées par notre système)
secret_key Votre clé secrète d'appel à notre systeme.
<?php
function validSec($values,
                  $secret_key)
?>

Librairie PHP

Exemple d'utilisation

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

Télécharger la librairie

TÉLÉCHARGER

Exemple rapide

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

Page d'appel

<?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>

Page de retour

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

Les valeurs de retours possibles sont :

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.

Démonstration

Aucun changement par rapport à un appel sans IPN à l'exception du paramètre supplémentaire (dans notre cas: http://localhost/ipn) qui représente la page à appeler après la validation du paiement bancaire client.

<?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>

Pour utiliser cet exemple vous devez créer un fichier ipn.php (fichier paramétré dans l'exemple). Celui-ci sera appelé automatiquement après la transaction bancaire. Il vous retournera un certain nombre d'informations :

  • idTpe
  • idTransaction
  • montant
  • result (OK / KO)
  • data
  • sec

L'Url de l'IPN est appelée dans tous les cas, que le paiement réussisse ou non, vous devez impérativement contrôler la valeur `result` et la valeur `sec` avant d'effectuer vos traitements.

Page de reception IPN

<?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

Cartes de test

Voici les cartes qui peuvent être utilisées pour simuler les différents encaissements en homologation :

Sans 3D Secure : Tout paiement strictement inférieur à 30€

Pour tout paiement supérieur ou égal à 30€ :

  • 3D Secure V1 : 2221001892683407
  • 3D Secure V2 avec authentification : 5306889942833340 > Le code à saisir dans la page d'authentification est 1234
  • 3D Secure V2 sans authentification ("frictionless") : 5512459816707530