Connecteur POST

De Documentation Mercanet
Aller à : navigation, rechercher

Paiement par carte via le connecteur POST

Schema connecteur post.png

  1. Appel de Mercanet :
    Le marchand fait l'appel à la page de paiement Mercanet en envoyant avec la méthode POST un formulaire contenant à minima les champs : Data, InterfaceVersion et Seal.
  2. Redirection sur la page de paiement Mercanet :
    Après vérification de l'intégrité des données reçues, Mercanet redirige le porteur sur :
    • la page de sélection des moyens de paiement puis,
    • la page de saisie des données carte.
  3. Demande d'autorisation et affichage de la réponse :
    Après la saisie des données cartes, une demande d'autorisation est réalisée auprès de la banque de l'acheteur (banque émettrice) et la réponse est ensuite affichée.
  4. Réponse automatique :
    Suite au résultat de la transaction, Mercanet envoie immédiatement une réponse automatique au serveur du marchand. Cette réponse est envoyée à l'URL qui est renseignée dans le champ automaticResponseUrl du champ Data.
  5. Réponse manuelle :
    Après que l'acheteur ait cliqué sur le bouton "Continuer" sur la page de résultat de la transaction, Mercanet effectue une redirection sur le serveur du marchand. L'acheteur est ainsi redirigé sur l'URL du marchand qui est renseignée dans le champ normalReturnUrl du champ Data.

Champs POST


Trois champs obligatoires sont à envoyer à Mercanet dans un formulaire en utilisant la méthode POST.

ChampsValeurDescription

Data

amount=1200|currencyCode=978|keyVersion=1|merchantId=211000021310001| transactionReference=123456|normalReturnUrl=https://www.marchand.com/normal_return.php

Contient les informations de la transaction

Format : <nom du champ 1>=<valeur 1>|<nom du champ 2>=<valeur 2>|...

InterfaceVersion

HP_2.18

Version de l’interface du connecteur.

Seal

17f3a0515bc90490bbf33cc0befde87c7e78f19ac4774c62ba62da12ed7a1d39

Vérification de l'intégrité des données transmises : champ calculé à partir des données du champ Data et de la clé secrète



Les champs ci-dessous peuvent être ajoutés en option et transmis avec la méthode POST :

ChampsValeurDescription

Encode

base64 ou
base64Url

Précise la méthode de codage utilisée dans le champ Data.

A utiliser dans le cas où le champ Data comporte des caractères spéciaux.

Puisque le calcul de la signature se fait dans le champ Data, il convient de noter qu’après l’application du codage, c’est la valeur encodée du champ Data qui sera utilisée pour les besoins du calcul.

SealAlgorithm

SHA-256 (par défaut) ou
HMAC-SHA-256 ou
HMAC-SHA-512

Précise l’algorithme utilisé pour chiffrer le sceau (champ Seal).

Info.pngA savoir :

Les noms des champs sont sensibles à la casse.


Construction du champ Data


Le champ Data est à envoyer dans la requête de paiement avec les données relatives à la transaction.

Le champ Data contient à minima les informations obligatoires ci-dessous :

 

Champ

Valeur

Description

amount

1200

A renseigner avec le montant de la transaction.
Dans notre exemple, la valeur correspond à 12.00€

currencyCode

978

Code ISO 4217 de la devise de la transaction
Dans notre exemple, la valeur correspond à la devise €

keyVersion

1

Version de la clé secrète récupérée dans Mercanet Téléchargement

merchantId

211000021310001

Identifiant de la boutique Mercanet

normalReturnUrl

https://www.marchand.com/normal_return.php

Traitement de retour manuel sur le site du commerçant

transactionReference 

123456

Identifiant unique de la transaction de paiement

 

Le champ Data est construit avec les champs de données de la requête à envoyer à Mercanet comme suit :
<nom du champ 1>=<valeur 1>|<nom du champ 2>=<valeur 2>|<nom du champ 3>=<valeur 3>|...
Exemple de champ Data à envoyer à Mercanet :
amount=1200|currencyCode=978|keyVersion=1|merchantId=211000021310001|transactionReference=123456|normalReturnUrl=https://www.commercant.com/normal_return.php


L’ordre des champs n’a pas d’importance.


Liste de valeurs :
…|nom du champ=valeur1,valeur2|…
Example avec paymentMeanBrandList :
…|amount=55|currencyCode=978|paymentMeanBrandList=VISA,MASTERCARD|…


Si le champ est un container, vous devez utiliser un point entre le nom du container et le nom du champ :
…|container.champ=valeur|…
Exemple avec customerContact :
…|customerContact.email=moi@email.com|customerContact.firstname=Jean|customerContact.lastname=Dupont|…

Calcul de la signature


Pour assurer l’intégrité des données envoyées par le commerçant vers Mercanet, les données émises sont signées afin de vérifier qu’elles n’ont pas été altérées et authentifier qu’il s’agit bien du commerçant.

Le calcul de la signature est basé sur un hash du champ Data par la clé secrète du commerçant.
Voici un exemple de calcul de la signature en PHP :

<?php
  $SecretKey = "S9i8qClCnb2CZU3y3Vn0toIOgz3z_aBi79akR30vM9o";
  $Data = "amount=1200|currencyCode=978|keyVersion=1|merchantId=211000021310001|transactionReference=123456|normalReturnUrl=https://www.marchand.com/normal_return.php";

  $DataToSend = utf8_encode($Data);              // conversion du champ Data en UTF8
  $Seal=hash('sha256', $DataToSend.$SecretKey);  // hash du champ Data en UTF8 
  
  echo "Seal = ".$Seal;
?>


Le résultat du Seal dans notre cas est : 17f3a0515bc90490bbf33cc0befde87c7e78f19ac4774c62ba62da12ed7a1d39

[Outil de calcul de la signature]

Accéder à Mercanet avec le connecteur POST

Le formulaire POST (constitué des 3 champs obligatoires) doit être envoyé avec la méthode POST (<form method="POST" ...>) à l'adresse d'appel de Mercanet constitué de :

  1. l'URL d'appel de Mercanet,
  2. le service utilisé.


Voici la liste des URL d'appel de Mercanet en fonction des différents environnements :

ContexteDescriptionURL d'appel de Mercanet
SIMU Boutique de simulation https://payment-webinit.simu.mercanet.bnpparibas.net
TEST Boutique de test https://payment-webinit-mercanet.test.sips-atos.com
PROD Boutique de production https://payment-webinit.mercanet.bnpparibas.net


En plus de l'URL d'accès à Mercanet, il faut ajouter le service en fonction de l'usage souhaité pour constituer l'adresse d'appel de Mercanet :

Description

Service

Appel de la page de paiement déportée

paymentInit

Gestion du Wallet

walletManagementInit


Voici par exemple l'URL d'appel de Mercanet utilisée pour appeler en production le service de paiement : https://payment-webinit.mercanet.bnpparibas.net/paymentInit

Exemples

Exemple simple d'appel de Mercanet

L'exemple simple ci-dessous, écrit en PHP, vous permet de comprendre comment envoyer une requête de paiement à Mercanet :

<?php
  // Génère un numéro de transaction aléatoire
  $transactionReference = "simu" . rand(100000,999999);
  // Construit l'URL de retour pour récupérer le résultat du paiement sur le site e-commerce du marchand
  $normalReturnUrl = "https://www.marchand.com/normal_return.php";
  // Contruit la requête des données à envoyer à Mercanet
  $data = "amount=100|currencyCode=978|merchantId=211000021310001|normalReturnUrl=".$normalReturnUrl."|transactionReference=".$transactionReference."|keyVersion=1";
  // Encode en UTF-8 des données à envoyer à Mercanet
  $dataToSend= utf8_encode($data);
  // Clé secrète correspondant au merchandId de simulation
  $secretKey = "S9i8qClCnb2CZU3y3Vn0toIOgz3z_aBi79akR30vM9o";
  // Calcul du certificat par un cryptage SHA256 des données envoyées suffixé par la clé secrète
  $seal=hash('sha256', $dataToSend.$secretKey);
  // Envoi des données à Mercanet par un formulaire POST
?>
<form method="post" action="https://payment-webinit-mercanet.test.sips-atos.com/paymentInit">
  <input type="hidden" name="Data" value="<?php echo $data; ?>">
  <input type="hidden" name="InterfaceVersion" value="HP_2.18">
  <input type="hidden" name="Seal" value="<?php echo $seal; ?>">
  <input type="submit" value="Payer"><br>
</form>

[Démonstration d'un paiement simple]

Exemple d'un paiement N fois

[Démonstration d'un paiement en n fois]

Exemple simple de traitement de la réponse de Mercanet

L'exemple simple ci-dessous, écrit en PHP, vous permet de comprendre comment réceptionner la réponse de Mercanet :

<?php
  $chaine = "";
  foreach($_POST as $k => $v)
  {
    if (strlen($v) > 0)
    {
      $chaine .= $k . '=' . $v ."<br>"; 
    }
  }
  echo "Retour = " . $chaine;
?>

Dans le programme de retour, il faut :

  • vérifier le seal retourné par Mercanet pour s'assurer que c'est bien Mercanet qui a fait la réponse au site e-commerce du marchand,
  • vérifier le résultat du paiement avec le champ responseCode contenu dans le champ POST Data
  • mettre à jour la commande du client avec le résultat du paiement

Kit de démarrage

Veuillez trouver ci-après des exemples de programmes plus complet écrit en PHP vous permettant de mettre en oeuvre l'appel à la page de paiement de Mercanet :

  • Kit pour le connecteur POST
    Vous pourrez tester les différents moyens de paiement:
    • Paiement differé
    • paiement N fois
    • Paiement One click
    • Paiement simple
    • Paiement avec choix du moyen de paiement
    • Retour url


  • Kit pour l'iFrame
    Vous pourrez tester l'affichage de la page de paiement en mode iFrame et voir le résultat du paiement :
    • sur Mercanet
    • sur le site marchand


  • Kit pour l'encodage
    Vous pourrez tester avec cet exemple :
    • l'appel de la page de paiement avec un encodage en base64 des données (utile par exemple pour transmettre des paramètres avec des accents),
    • le retour des paramétres envoyés par Mercanet avec un encodage en base64.


Il vous suffit pour cela de télécharger l'un des fichier zip ci-dessus, de décompresser le contenu du fichier zip et de mettre le contenu sur votre serveur Web.

Paramétrer la requête de paiement

Voici un exemple de paramétrage de la requête de paiement pour chaque fonctionnalité disponible dans le connecteur POST (le détail de ces fonctionnalités est décrit dans le guide des fonctionnalités).

Affichage dynamique des moyens de paiement

Il faut filtrer ceux qui s’afficheront dans la page de sélection des moyens de paiement grâce au champ paymentMeanBrandList:

..|paymentMeanBrandList=VISA,PAYPAL|..

Données retournées dans les flux retours et les journaux

Pour transmettre des données avec votre transaction dans les flux retours automatiques et manuels ainsi que dans les journaux, vous pouvez alimenter le champ returnContext:

..|returnContext=valeurTransmise|..

Affichage du ticket par Mercanet

La page de confirmation du paiement, affichée par défaut par Mercanet peut être désactivée. Cette désactivation se fait par le champ paypageData.bypassReceiptPage:

..|paypageData.bypassReceiptPage=Y|..

Canal de paiement

Pour choisir votre canal de paiement, vous devez remplir le champ orderChannel dans la requête de paiement:

…|orderChannel= INTERNET|..

Paiement en fin de journée

Dans le cas d’un paiement en fin de journée, il suffit de remplir les champs captureMode et captureDay:

…|captureDay=0|captureMode=AUTHOR_CAPTURE|..

Paiement différé

Dans le cas d’un paiement à remiser N jours après l’acceptation en ligne, il suffit de remplir les champs captureMode et captureDay(3 jours dans notre exemple) :

…|captureDay=3|captureMode=AUTHOR_CAPTURE|..
<pre>
===Paiement à l’expédition===
Dans le cas d’un paiement à l’expédition, la transaction est envoyée en paiement lors votre validation, il faut juste remplir les champs captureMode et captureDay(3 jours de délai possible avant validation dans notre exemple) :
<pre>
…|captureDay=3|captureMode=VALIDATION|..

Paiement échelonné

Dans le cas d’un paiement en plusieurs échéances liées à une même transaction, il faut renseigner le champ paymentPattern à INSTALMENT et fournir le détail des échéances dans le champ instalmentData (600€ payés en 3 échéances dans notre exemple) :

…|amount=60000|…|transactionReference=tref1|…|paymentPattern=INSTALMENT|instalmentData.number=3|instalmentData.datesList=20170412,20170512,20170612|instalmentData.transactionReferencesList=tref1,tref2,tref3|instalmentData.amountsList=10000,30000,20000|..

Paiement immédiat

Si vous souhaitez un paiement immédiat (disponible uniquement pour certains moyens de paiement), la transaction est payée lors de l’autorisation en ligne :

…|captureMode=IMMEDIATE|..

Acceptation multidevises

Dans le casdes transactions multidevises le code devise doit être spécifié dans la requête. C’est dans le contrat d’acquisition qu’est précisée la devise de règlement.

…|currencyCode=840|..

Règlement en devises

L’acceptation et le règlement sont effectués dans la même devise qui doit être spécifiée dans la requête. Le règlement en devises est une option du contrat d’acquisition.

…|currencyCode=826|..

Conversion dynamique des devises (DCC)

Dans le cas où un service financier de conversion dynamique de devise (DCC) est utilisé, le code devise de référence doit être spécifié:

…|currencyCode=978|..

Débrayage dynamique du 3D Secure

Pour désactiver dynamiquement l’authentification 3D Secure, il faut spécifier cette action dans le champ fraudData.bypass3DS:

…|fraudData.bypass3DS=ALL|..

Débrayage 3D Secure pour paiement Oneclick

Pour désactiver dynamiquement l’authentification 3D Secure pour les paiements en One click, il faut spécifier cette action dans le champ fraudData.bypass3DS:

…|fraudData.bypass3DS= MERCHANTWALLET|..

Inscription et paiement Oneclick

Pour un paiement One click, l’identifiant du wallet du client doit être renseigné dans le champ merchantWalletId.

…|merchantWalletId=1205987|..

Prestataire agissant pour le compte d’un commerçant

Il faut passer l’identifiant du prestataire dans la requête dans le champ intermediateServiceProvider et utiliser la clé secrète de ce dernier pour calculer la donnée Seal:

..|intermediateServiceProviderId=241591|..

Données échangées avec Mercanet

Vous trouverez dans l'interface POST , la liste des champs :

Exemple de réponse

Mercanet retourne par POST les mêmes champs Data, Seal et InterfaceVersion avec en retour les informations sur la transaction :

Data=captureDay=0|captureMode=AUTHOR_CAPTURE|currencyCode=978|merchantId=211000021310001|orderChannel=INTERNET|responseCode=00|transactionDateTime=2016-12-30T16:03:19+01:00|transactionReference=test337624|keyVersion=1|acquirerResponseCode=00|amount=100|authorisationId=368530|panExpiryDate=201701|paymentMeanBrand=VISA|paymentMeanType=CARD|complementaryCode=00|complementaryInfo=<RULE_RESULT SC=0 />,<CARD_INFOS BDOM=XXX COUNTRY=FRA PRODUCTCODE=F NETWORK=VISA BANKCODE=20041 PRODUCTNAME=VISA CLASSIC PRODUCTPROFILE=XXX />|customerIpAddress=159.50.252.71|maskedPan=5017##########02|returnContext=123456|scoreProfile=11_GONOGO_PRE_AUTHORISATION|holderAuthentRelegation=N|holderAuthentStatus=NO_AUTHENT|transactionOrigin=INTERNET|paymentPattern=ONE_SHOT|customerMobilePhone=null|mandateAuthentMethod=null|mandateUsage=null|transactionActors=null|mandateId=null|captureLimitDate=20161230|dccStatus=null|dccResponseCode=null|dccAmount=null|dccCurrencyCode=null|dccExchangeRate=null|dccExchangeRateValidity=null|dccProvider=null|statementReference=null|panEntryMode=MANUAL|walletType=null|holderAuthentMethod=NO_AUTHENT_METHOD|holderAuthentProgram=NO_AUTHENT|paymentMeanId=null|instalmentNumber=null|instalmentDatesList=null|instalmentTransactionReferencesList=null|instalmentAmountsList=null|settlementMode=null|mandateCertificationType=null|valueDate=null|creditorId=null|acquirerResponseIdentifier=null|acquirerResponseMessage=null|paymentMeanTradingName=null|additionalAuthorisationNumber=null|issuerWalletInformation=null|s10TransactionId=794066|s10TransactionIdDate=20161230|preAuthenticationColor=null|preAuthenticationInfo=null|preAuthenticationProfile=null|preAuthenticationThreshold=null|preAuthenticationValue=null|invoiceReference=null|s10transactionIdsList=null|cardProductCode=F|cardProductName=VISA CLASSIC|cardProductProfile=null|issuerCode=20041|issuerCountryCode=FRA|acquirerNativeResponseCode=00|settlementModeComplement=null|preAuthorisationProfile=11_GONOGO_PRE_AUTHORISATION|preAuthorisationProfileValue=unknown|preAuthorisationRuleResultList=[{"ruleCode":"SC","ruleType":"NG","ruleWeight":"D","ruleSetting":"I","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:5;CUMUL=100:X"}]|preAuthenticationProfileValue=null|preAuthenticationRuleResultList=null|paymentMeanBrandSelectionStatus=null|transactionPlatform=PROD

Seal=f9d0a4a11b046113c75285213fd772b9207d2861d4dfd46f1fda33136221c2d4

InterfaceVersion=HP_2.18

Réponses de Mercanet

Le marchand doit renseigner dans sa requête envoyée à Mercanet les URL de réponses manuelle et automatique pour vérifier si le paiement a été réalisé avec succès ou non.

Réponse manuelle

Le marchand doit obligatoirement renseigner une réponse manuelle pour que le porteur soit redirigé vers cette URL du marchand à la fin du paiement.

Cette URL du marchand est à renseigner dans le champ normalReturnUrl.

L'appel de cette URL du marchand ne signifie pas que le paiement soit réalisé et accepté.

Cette URL du marchand est appelé dans les cas suivants :

  • quand le porteur clique sur le bouton "Continuer" sur la page de résultat du paiement affichée par Mercanet
  • quand le porteur clique sur le bouton "Annuler" sur la page de saisie des informations de la carte

Warning sign.pngAttention :
Il faut savoir que le porteur peut :

  • ne pas cliquer sur le bouton "Continuer" à la fin du paiement,
  • avoir un problème de connexion réseau qui empêche la redirection cette URL du marchand.

C'est pour cela qu'à été ajouté une réponse automatique pour informer systématiquement le serveur du marchand du résultat du paiement.

Réponse automatique

La réponse automatique est le seul moyen pour assurer le marchand qu'un retour soit envoyé systématiquement vers son serveur à la fin de la transaction.

Le contenu de la réponse automatique est le même que celui de la réponse manuelle.

L'URL du marchand, appelée pour une réponse automatique, est à renseigner dans le champ automaticResponseUrl.

Warning sign.pngAttention :
Le marchand doit veiller à ne pas créer des commandes en double sur son serveur marchand suite à la réception des 2 réponses envoyées par Mercanet : réponse manuelle et automatique.

Contrôle des réponses

Les réponses manuelles et automatiques doivent être impérativement contrôlées par le marchand car ce n'est pas parce qu'une réponse est réceptionnée qu'elle provient forcément de Mercanet.

C'est pour cela que la signature de la réponse envoyée par Mercanet doit être contrôlée par le marchand afin de s'assurer de la provenance et de l'intégrité des données réceptionnées.

Le marchand doit donc vérifier que le champ Seal envoyé par Mercanet correspond bien à la signature du champ Data de la même façon que pour l'appel de Mercanet.

Ne pas afficher la page de résultat de Mercanet

Il est donné la possibilité au marchand d'afficher lui-même le résultat du paiement à la place de Mercanet.

Dans ce cas :

  • la page de résultat du paiement n'est pas affichée par Mercanet,
  • l'URL de réponse manuelle est appelée directement sans action du poteur à la fin de la transaction.


Le marchand peut ainsi raccourcir le tunnel de paiement et afficher un ticket de paiement pour le porteur depuis son site marchand.

Analyser la réponse de paiement

Etat

Champs de la réponse

Action à réaliser

Paiement accepté

responseCode = 00
acquirerResponseCode = 00
garanteeIndicator = Y,N,U, vide

Vous pouvez livrer la commande en fonction du niveau de garantie que vous souhaitez (champ garanteeIndicator)

Refus Fraude Sips GONOGO

responseCode = 05
complementaryCode = XX
preAuthorisationRuleResultList

Le paiement a été refusé par le moteur de fraude Sips que vous avez configuré. Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par Sips pour connaitre la cause du refus (champ preAuthorisationRuleResultList).

Refus Fraude Sips GONOGO

responseCode = 05
complementaryCode = XX
preAuthorisationRuleResultList

Le paiement a été refusé par le moteur de fraude Sips que vous avez configuré. Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par Sips pour connaitre la cause du refus (champ preAuthorisationRuleResultList).

Refus Fraude Sips BUSINESS SCORE

responseCode = 05
scoreColor = RED, BLACK
scoreValue = X (score de la transaction)
scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été refusé par le moteur de fraude Sips que vous avez configuré Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par Sips pour connaitre la cause du refus (champ preAuthorisationRuleResultList).

Warning Fraude Sips BUSINESS SCORE

responseCode = 05
scoreColor = ORANGE
scoreValue = X (score de la transaction)
scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été autorisé par l’acquéreur mais le moteur de fraude Sips émet un warning par rapport aux règles que vous avez configurées. Analysez le détail des règles fraudes exécutées par Sips pour connaitre la cause du warning (champ preAuthorisationRuleResultList). Si transaction non risquée alors acceptez la avec la fonction acceptChallenge. Si transaction risquée alors refusez la avec la fonction refuseChallenge. Les fonctions acceptChallenge et refuseChallenge sont disponibles sur l’extranet et les connecteurs office.

Refus 3D Secure

reponseCode = 05
holderAuthenStatus = FAILURE

L’authentification de l’acheteur a échoué, ce n’est pas nécessairement un cas de fraude. Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête

Refus bancaire acquéreur

responseCode = 05
acquirerResponseCode = XX

L’autorisation est refusée pour un motif non lié à la fraude. Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête.

Refus fraude acquéreur

responseCode = 34
acquirerResponseCode = XX

Autorisation refusée pour cause de fraude. Ne livrez pas la commande.

Refus nombre max essais atteint

responseCode = 75
acquirerResponseCode = XX

L’acheteur a fait plusieurs tentatives toutes échouées car les informations saisies n’étaient pas correctes. Deux possibilités : Difficulté pour votre client pour renseigner les informations cartes Tentative de carding (recherche de numéros de cartes possibles) Prenez contact avec votre client pour définir la suite à donner.

Refus suite problème technique

responseCode = 90, 99
acquirerResponseCode = 90 à 98

Problème technique temporaire lors du traitement de la transaction. Proposez à votre client de refaire un paiement ultérieurement.