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/psp.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 clef 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
montant Montant de la transaction 10.00
idTPE Identifiant de votre TPE ComNpay DEMO
idTransaction Référence unique de transaction 123456-DEMO-A456456
devise Devise de la transaction EUR
lang Langue de la page de paiement fr
nom_produit Nom du produit Mon Produit
urlRetourOK URL de redirection après paiement accepté http://votresite/landingOK.html)
urlRetourNOK URL de redirection après paiement refusé http://votresite/landingNOK.html)
urlIPN En savoir plus sur l'IPN http://votresite/ipn
data Valeur non traitée par ComNpay, simplement renvoyée via l'IPN  
typeTr Type de transaction D : Débit, PA : Pré-autorisation, P3F : Paiement en 3 fois
sec Valeur calculée par votre serveur le champ SEC
titrePreauto Personnalisation titre "Information pré-autorisation"  
messagePreauto Personnalisation message en infobulle dans le cas d'une pré-autorisation  
titreAls Personnalisation titre "Identification de votre carte"  
messageAls Personnalisation message en infobulle dans le cas d'une identification de carte  
messageUserFields Personnalisation message invitant l'utilisateur à indiquer des informations personnelles complémentaires  
porteur Permet l'envoi d'informations sur le porteur, que vous retrouverez dans votre back office AfonePaiement {"nom": "Janvier", "prenom": "Thomas","email": "tjanvier@comnpay.com", "telephone": "0606060606", "adresse": "5 Place Albert Durand", "codePostal": "49100", "ville": "Angers","pays": "France"} JSON à envoyer encodé en base 64

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 clef secrete n'est pas présente.) */
  $array_tpe

  /* On ajoute la clef secrete aux valeurs. La clef secrete nous sert uniquement à signer la liste des valeurs. */
  $array_tpe['key'] = "CLEF SECRETE"

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

  /* On retire la clef secrete */
  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 clef SEC notre système refusera la transaction.
  */
  $array_tpe['sec'] = hash("sha512",$strWithKey)
?>

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

Types de transactions

Le champs typeTr accepte trois valeurs :

  • 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)

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çu 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 / NOK)
  • 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