logo Mercanet

Release 24.6

aller directement au contenu

Rechercher par mots clés

Guide de démarrage rapide

Pour rechercher dans la page utiliser Ctrl+F sur votre clavier

Ce document s’adresse aux commerçants qui souhaitent une intégration rapide et simple de la solution Mercanet. Il vous permet de démarrer avec le connecteur Mercanet Paypage POST sans personnalisation des pages de paiement.

Les options décrites dans ce guide sont les plus couramment utilisées.

Ce guide vous explique comment accepter des paiements :

  • en euros ;
  • avec les moyens de paiement Visa, Vpay, Electron, Mastercard, Maestro et PayPal ;
  • sécurisés par 3-D Secure.

Vous utilisez Mercanet Back Office pour la gestion de caisse et recevez quotidiennement les journaux par mail.

Ce document est valable pour la version 2.18 du connecteur et les versions ultérieures.

Une connaissance élémentaire des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion à Mercanet Paypage POST.

Note: toutes les portions de code de ce document sont fournies à titre d’exemple, il convient de les adapter à votre site Web afin qu’elles soient pleinement exploitables.

Lors de votre inscription, BNP Paribas met à disposition sur Mercanet Téléchargement (voir l'annexe "Télécharger la clé secrète"), une clé secrète qui permet de sécuriser les échanges entre votre site et le serveur Mercanet.

Vous êtes responsable de sa conservation et devez prendre toutes les mesures pour :

  • en restreindre l'accès ;
  • la sauvegarder de manière chiffrée ;
  • ne jamais la copier sur un disque non sécurisé ;
  • ne jamais l'envoyer (e-mail, courrier) de manière non sécurisée.

Mercanet est une solution de paiement e-commerce multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d’accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à votre activité (paiement à la livraison, paiement différé, paiement récurrent, paiement en plusieurs fois, …).

Vous gardez le choix de votre établissement bancaire et des moyens de paiement acceptés.

Quotidiennement, Mercanet envoie par mail les journaux d’activité :

  • Le journal des transactions qui récapitule l’ensemble des transactions acceptées ou refusées.
  • Le journal des opérations qui récapitule les opérations de caisse que vous avez effectuées.
  • Le journal de rapprochement des transactions qui donne la vue financière des paiements crédités sur vos comptes.
  • Le journal de rapprochement des impayés qui rapproche les impayés de l’établissement bancaire (ex. contestation porteur) avec les transactions que vous avez acceptées.

Mercanet propose l’interface Paypage pour connecter votre site Web à la plateforme de paiement.

Paypage assure l’interface de paiement directement avec votre client via un navigateur Internet ou un mobile.Paypage met donc à votre disposition des pages de paiements sécurisées, prêtes à l’emploi et accessibles par vos clients.

Paypage s’accompagne d’une interface web de gestion de caisse : Mercanet Back Office. Elle vous permet de créer et gérer vos transactions. (validation, annulation, remboursement, ….)



Ref Nom Fréquence Description
a1 Requête de paiement Paypage 24h/24h Requête de paiement envoyée par vous au serveur Mercanet
a2 Réponse automatique 24h/24h Réponse du serveur Mercanet qui vous est envoyée une fois le paiement effectué. Envoi automatique indépendant de l’action du client. En cas d'abandon du client, vous recevrez la réponse automatique environ 15 minutes après la redirection du client vers les pages de paiement Mercanet
a3 Réponse manuelle 24h/24h Réponse du serveur Mercanet qui vous est envoyée lorsque le client clique sur « continuer ». Envoi conditionné par l’action du client.
d1 Authentification du porteur 24h/24h Requête envoyée au serveur d’authentification 3-D Secure de la banque du porteur
e1 Demande d’autorisation 24h/24h Demande d’autorisation envoyée à votre établissement bancaire
e2 Remise en paiement 1/jour Remise en paiement envoyé par Mercanet vers l’établissement bancaire pour vous créditer
e3 Retour du paiement 24h/24h Retour de l’établissement bancaire sur le traitement d’acquisition des paiements
b Gestion de caisse 24h/24h Opération de caisse envoyée par vous au serveur Mercanet
c Journaux 1/jour Journaux envoyés par mail


Le parcours client est le suivant :

  • Validation du panier de votre page commerçant,
  • Redirection du client sur la page Mercanet de sélection du moyen de paiement,
  • Saisie des données carte,
  • Authentification du client sur une page de sa banque (si 3-D Secure),
  • Affichage du ticket de caisse par Mercanet,
  • Confirmation de la prise en compte de la commande sur votre page commerçant.

Dans cette cinématique que la saisie des données de la carte s'effectue chez Mercanet.Vous n’avez pas connaissance de ces données sensibles.



Le parcours client est le suivant :

  • Validation du panier sur votre page commerçant
  • Redirection du client sur la page de sélection du moyen de paiement Mercanet
  • Identification du client sur une page PayPal et validation du moyen de paiement
  • Affichage du ticket de caisse par Mercanet
  • Confirmation de la prise en compte de la commande sur votre page commerçant

Les transactions de votre boutique sont identifiées de manière unique grâce au champ transactionReference.

Cet identifiant est calculé par Mercanet ou par vous lors de la création de la transaction. Le couple (transactionReference, merchantId) identifie de manière unique la transaction pendant toute la vie de la transaction.

Pour accepter des paiements via Mercanet vous devez avoir préalablement signé :

  • un contrat de vente à distance e-commerce/vente par correspondance (VPC) avec votre banque ;
  • un contrat d’acceptation avec le revendeur de la solution Mercanet ;

La souscription au service 3-D Secure de Visa et MasterCard qui sécurise les paiements internet est une clause obligatoire du contrat de vente à distance avec votre banque.

Pour pouvoir accepter les paiements PayPal, vous devez également avoir signé un contrat avec PayPal. Votre compte commerçant PayPal doit également être configuré de manière à autoriser l’appel à Mercanet (cf annexe "paramétrer son compte PayPal").

Afin d’inscrire votre boutique, vous devez remplir le formulaire d’inscription envoyé par BNP Paribas et le retourner à ce dernier.

Lors de la saisie du formulaire, vous désignez un contact administratif et un contact technique afin que BNP Paribas puisse vous communiquer les informations nécessaires pour démarrer votre boutique.

BNP Paribas procède alors à l’enregistrement de la boutique et vous retourne votre identifiant commerçant (merchantId) ainsi que vos identifiants et mots de passe Merchant Extranet (récupération de la clé secrète et gestion de caisse).

Note: Pour Merchant Extranet, les informations de connexion sont envoyées au contact administratif.

L’inscription de la boutique n’est pas nécessaire pour commencer à intégrer le connecteur et à tester la connexion sur l’environnement de simulation. Vous pouvez ne demander l’inscription de votre boutique qu’au moment de faire les tests en production.

Vous devez intégrer le connecteur Mercanet Paypage POST pour connecter votre site commerçant au serveur de paiement Mercanet.

Vous devez donc mettre en place les liens a1 (requête de paiement), a2 et a3 (réponse de paiement automatique et manuelle) décrits dans ce schéma :



Attention: bien que la réponse automatique ne soit pas obligatoire, il est fortement conseillé de l’implémenter.

Si le client ne clique pas sur « continuer », la réponse manuelle ne sera pas envoyée et vous n’aurez pas de réponse venant de Mercanet vous confirmant le traitement de la transaction.

Note: pour vous aider à vous connecter à Mercanet, vous pouvez consulter les exemples de code présents sur notre dépôt GitHub.

La requête paiement est envoyée depuis une page de votre site web vers le serveur Mercanet via un formulaire web avec la méthode POST. Ce formulaire doit pointer vers l’URL du serveur de paiement Mercanet et contenir les champs suivants :

Donnée du formulaire Présence Description
Data Obligatoire Ensemble des champs de la requête de paiement (champs décrits ci-dessous dans la partie « construire la requête de paiement : donnée Data »)
InterfaceVersion Obligatoire L’interface version définit la version de la requête et de la réponse échangée avec le serveur de paiement. Les champs décrits ci-après correspondent à la dernière interfaceVersion. Si vous utilisez une version antérieure du connecteur, il est possible que certains champs ne soient pas disponibles et ne puissent être utilisés.
Seal Obligatoire Signature de la donnée Data qui permet de garantir la sécurité de la requête de paiement
Encode Optionnel Dans le cas où la donnée Data comporte des caractères spéciaux, vous devez changer l’encodage. La valeur du champ Encode précise la méthode d’encodage utilisée pour la donnée Data. En cas d’encodage, le seal est calculé sur la donnée data encodé.

Valeurs:

  • Base64 : encodage du champ data en base 64
  • Base64URL : encodage du champ data en base64URL
SealAlgorithm Optionnel Algorithme utilisé pour le calcul de l’empreinte de la donnée Data

Valeurs :

  • HMAC-SHA-256 : L'algorithme utilisé est HMAC-SHA-256
  • HMAC-SHA-512 : L'algorithme utilisé est HMAC-SHA-512
  • SHA-256 : L'algorithme utilisé est SHA-256
Tip: par défaut, le sceau est calculé avec l'algorithme SHA-256, pour qu’un sceau soit calculé avec l'algorithme HMAC-SHA-256, les paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm avec la valeur suivante : HMAC-SHA-256.

La donnée Data est composée de plusieurs champs, elle contient toutes les informations relatives à la transaction.

Elle est fournie sous la forme d’une chaîne de caractères respectant la syntaxe suivante :

<nomChamp1>=<valeurChamp1>|<nomChamp2>=<valeurChamp2>|… |<nomChampN>=<valeurChampN>

La donnée Data est composée des champs suivants :

  • Champs obligatoires
Champs Format Description
amount N12 Montant de la transaction. Il doit être transmis dans la plus petite unité de la devise. Ex : pour l’Euro, un montant de 10,50€ doit être transmis sous la forme 1050.
currencyCode N3 (restricted values / ISO4217) Code de la devise de la transaction. Ce code est compatible ISO 4217. Ex : le code de l’euro est 978.
keyVersion N10 Version de la clé secrète du commerçant utilisée pour calculer le seal du message. Ex : KeyVersion=1 pour la 1ère clé générée à l’inscription de la boutique.
merchantId N15 Identifiant de la boutique, fourni par Mercanet au commerçant lors de l’inscription de sa boutique.
normalReturnUrl ANS512 (url) URL du commerçant pour le retour à la boutique en cas d’acceptation ou de refus de la transaction (réponse manuelle). Ex : https://www.monsite.fr/RetourPaiement
automaticResponseUrl ANS512 (url) URL fournie par le commerçant et utilisée par le serveur de paiement pour notifier au commerçant de manière online et automatique le résultat de la transaction (réponse automatique).

NB : champ non obligatoire mais utilisation fortement recommandée pour que vous receviez la réponse de paiement même si le client ne clique pas sur « continuer »

  • Principaux champs métiers facultatifs qui vous permettent de faciliter la correspondance entre votre système d’information et le serveur de paiement Mercanet
Champs Format Description
customerId ANS19 (restrictedString) Identifiant du client
customerEmail ANS128 (email) E-mail du client
orderId ANS32 Numéro de commande associé à la transaction de paiement.
returnContext ANSU255 (extendedString) Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions. Vous pouvez y stocker toute les informations qui facilitent le traitement de la réponse.
  • Champs CB, Visa, Mastercard, Vpay, Electron et Maestro : Pas de champ spécifique
  • Champs PayPal (champs disponibles depuis la version HP_2.18)
Champs Format Description
addrOverride ANS20 (restricted values) Indicateur vous permettant :
  • d’afficher l’adresse de livraison sur les pages PayPal,
  • de savoir, si l’adresse à afficher est celle que vous communiquez ou s’il s’agit de celle stockée par PayPal
  • de déterminer si vous pouvez modifier l’adresse stockée par PayPal.

Valeurs :

  • NO_OVERRIDE : PayPal affiche l'adresse enregistrée par le client sur son compte PayPal.
  • OVERRIDE : PayPal affiche l'adresse communiquée par le commerçant, l'adresse enregistrée par le client sur son compte PayPal est supprimée.
  • NO_DISPLAY (Valeur par défaut) : Aucune adresse n'est affichée. L'adresse envoyée par le commerçant n'est pas prise en compte par PayPal
invoiceId AN127 Numéro de commande, équivaut à l’orderId mais doit être unique chez PayPal. Obligatoire pour l’utilisation de PayPal.
landingPage AN5 (restricted values) Indicateur vous permettant de masquer le formulaire de souscription sur les pages PayPal.

Valeurs :

  • true : La page de souscription est affichée
  • false : La page de souscription n'est pas affichée, PayPal affiche directement la page d'identification
mobile AN5 (restricted values) Indicateur vous permettant de préciser si le terminal utilisé par le client est le mobile

Valeurs :

  • true : L'appareil utilisé est un mobile
  • false : L'appareil utilisé n'est pas un mobile
orderDescription ANS127 Description de la commande

La requête contient les paramètres de la transaction et est envoyée par le navigateur Web du client. Il est théoriquement possible pour un pirate d’intercepter la demande et de la modifier avant l’envoi au serveur de paiement.

De ce fait, il est nécessaire de renforcer la sécurité pour assurer l’intégrité des paramètres de la transaction envoyée. Mercanet répond à ce besoin par un échange de signatures qui permet de vérifier :

  • l’intégrité des messages requête et réponse ;
  • l’authentification de l’émetteur et du destinataire car ils se partagent la même clé secrète.
IMPORTANT: si votre clé secrète est compromise, ou si vous supposez que c’est le cas, vous devez impérativement demander son renouvellement en vous connectant à Mercanet Téléchargement.

La sécurisation de la requête est effectuée en calculant la valeur « hashée » conformément aux paramètres de la transaction (donnée Data). Ensuite, la clé secrète y est ajoutée. Toutes les chaînes de caractères sont converties en UTF-8 avant le « hashage ».

L’algorithme de « hashage » génère un résultat irréversible qui doit être envoyé sous forme hexadécimale dans le champ POST nommée Seal.

Lorsque le message est reçu, le destinataire doit recalculer la valeur « hashée » pour la comparer à celle reçue. Toute différence indique que les données échangées ont été falsifiées.

Il existe 2 méthodes pour signer l’empreinte de la donnée Data :

Pour l’algorithme HMAC-SHA256 :

  • Utilisation de la donnée Data uniquement (encodée si l’option correspondante est choisie)
  • Utilisation de la clé secrète partagée pour générer la variante HMAC du message
  • Codage UTF-8 des données constituant le résultat de l’opération précédente
  • « Hashage » HMAC-SHA256 des octets obtenus
HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))

Pour l’algorithme SHA-256 (bien que celui-ci soit la valeur par défaut, cet algorithme n’est plus recommandé à ce jour) :

  • Concaténation du champ Data et de la clé secrète (encodée si l’option correspondante est choisie)
  • Codage UTF-8 des données constituant le résultat de l’opération précédente
  • « Hashage » SHA256 des octets obtenus
SHA256( UTF-8(Data+secretKey))
  • Exemple d’encodage Hmac Sha256 en Php 5
    <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    
    $data_to_send= utf8_encode($data)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 

    data_to_send et secretKey doivent utiliser un jeu de caractères UTF-8. Référez-vous à la fonction utf8_encode pour la conversion de caractères ISO-8859-1 en UTF-8.

  • Exemple d’encodage Hmac Sha256 en Java
    import java.security.InvalidKeyException;
    import java.security.NoSuchAlgorithmException;
    
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class ExampleHMACSHA256 {
    
    /**
     * table to convert a nibble to a hex char.
     */
    static final char[] hexChar = {
       '0' , '1' , '2' , '3' ,
       '4' , '5' , '6' , '7' ,
       '8' , '9' , 'a' , 'b' ,
       'c' , 'd' , 'e' , 'f'};
    
    /**
     * Fast convert a byte array to a hex string
     * with possible leading zero.
     * @param b array of bytes to convert to string
     * @return hex representation, two chars per byte.
     */
    public static String encodeHexString ( byte[] b )
       {
       StringBuffer sb = new StringBuffer( b.length * 2 );
       for ( int i=0; i<b.length; i++ )
          {
          // look up high nibble char
          sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );
    
          // look up low nibble char
          sb.append( hexChar [b[i] & 0x0f] );
          }
       return sb.toString();
       }
    
    /**
     * Computes the seal
     * @param Data the parameters to cipher
     * @param secretKey the secret key to append to the parameters 
     * @return hex representation of the seal, two chars per byte.
     */
    public static String computeSeal(String data, String secretKey) throws Exception
    {
      Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
      SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      hmacSHA256.init(keySpec);
    
      return encodeHexString(hmacSHA256.doFinal(data.getBytes()));
    }
    
    /**
     * @param args
     */
    public static void main(String[] args) {
    try {
    System.out.println (computeSeal("parameters", "key"));
    } catch (Exception e) {
    e.printStackTrace();
    }
    }
    
    }
  • Exemple d’encodage Hmac Sha256 en .net

    (Exemple effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir data et txtSecretKey, ainsi qu’un autre champ pour afficher lblHEX).

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;
    using System.Security.Cryptography;
    
    namespace ExampleDotNET
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }
    
            private void cmdGO_Click(object sender, EventArgs e)
            {
                String sChaine = data.Text;
                UTF8Encoding utf8 = new UTF8Encoding();
                Byte[] encodedBytes = utf8.GetBytes(sChaine);
            
                byte[] shaResult;
                
                HMAC hmac = new HMAC.Create("HMACSHA256");
                var key = "YourSecretKey";
                hmac.Key = utf8.GetBytes(key); 
                hmac.Initialize();
    
                shaResult = hmac.ComputeHash(encodedBytes);
    
                lblHEX.Text = ByteArrayToHEX(shaResult);
            }
    
            private string ByteArrayToHEX(byte[] ba)
            {
                StringBuilder hex = new StringBuilder(ba.Length * 2);
                foreach (byte b in ba)
                    hex.AppendFormat("{0:x2}", b);
                return hex.ToString();
            }
    
        }
    }
  • Exemple d’encodage Sha256 en Php 5
<?php
echo hash('sha256', $data.$secretKey);
?> 

Le jeu de caractères UTF-8 doit être utilisé pour les données Data et secretKey. Pour effectuer une conversion de ISO-8859-1 à UTF-8, faites appel à la fonction utf8_encode.

  • Exemple d’encodage Sha256 en Java
import java.security.MessageDigest;

public class ExampleSHA256 {

/**
 * table to convert a nibble to a hex char.
 */
static final char[] hexChar = {
   '0' , '1' , '2' , '3' ,
   '4' , '5' , '6' , '7' ,
   '8' , '9' , 'a' , 'b' ,
   'c' , 'd' , 'e' , 'f'};

/**
 * Fast convert a byte array to a hex string
 * with possible leading zero.
 * @param b array of bytes to convert to string
 * @return hex representation, two chars per byte.
 */
public static String encodeHexString ( byte[] b )
   {
   StringBuffer sb = new StringBuffer( b.length * 2 );
   for ( int i=0; i<b.length; i++ )
      {
      // look up high nibble char
      sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );

      // look up low nibble char
      sb.append( hexChar [b[i] & 0x0f] );
      }
   return sb.toString();
   }

/**
 * Computes the seal
 * @param Data the parameters to cipher
 * @param secretKey the secret key to append to the parameters 
 * @return hex representation of the seal, two chars per byte.
 */
public static String computeSeal(String Data, String secretKey) throws Exception
{
  MessageDigest md = MessageDigest.getInstance("SHA-256");
  md.update((Data+secretKey).getBytes("UTF-8"));

  return encodeHexString(md.digest());
}

/**
 * @param args
 */
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}
}
  • Exemple d’encodage Sha256 en .NET

Exemple complété à l’aide d’un simple formulaire appelé « Form 1 » contenant deux champs de texte à renseigner : data, txtSecretKey et un autre à afficher : lblHEX.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Security.Cryptography;

namespace ExampleDotNET
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void cmdGO_Click(object sender, EventArgs e)
        {
            String sChaine = data.Text + txtSecretKey.Text;
            UTF8Encoding utf8 = new UTF8Encoding();
            Byte[] encodedBytes = utf8.GetBytes(sChaine);
        
            byte[] shaResult;
            SHA256 shaM = new SHA256Managed();
            shaResult = shaM.ComputeHash(encodedBytes);

            lblHEX.Text = ByteArrayToHEX(shaResult);
        }

        private string ByteArrayToHEX(byte[] ba)
        {
            StringBuilder hex = new StringBuilder(ba.Length * 2);
            foreach (byte b in ba)
                hex.AppendFormat("{0:x2}", b);
            return hex.ToString();
        }

    }
}

La demande de paiement est une requête HTTPS POST adressée à Mercanet Paypage POST.

Exemple de requête dans le formulaire Web (Data non encodé. Les champs optionnels sealAlgotrihm et encode ne sont pas renseignés).

<form method="post" action="https://url.vers.serveur.sips/paymentInit"> 
    <input type="hidden" name="Data" value="amount=55|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transactionReference=534654|keyVersion=1">
    <input type="hidden" name="InterfaceVersion" value="HP_2.18"> 
    <input type="hidden" name="Seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c0592044d4"> 
    <input type="submit" value="Payer">
</form>

Voici une liste des erreurs que vous pourriez rencontrer et les messages pour chacun de ces cas. Si l’erreur persiste, contactez l’assistance.

Etat Exemple de message d’erreur Action à réaliser
MerchantId inexistant Merchant ID (merchantId) not found : findMerchantPoi [220555555550002] is not found [5c62b84e3ae83d] Vérifiez le merchantId utilisé avec celui retourné par Mercanet après l’inscription.
Algorithme de seal incorrect Invalid field value : Invalid sealAlgorithm value (SHA-257) [609eac90a8ee1e]] Vérifiez l’algorithme seal utilisé (champ seal)
Erreur clé secrète Invalid signature : rge7gesgd86g556dgv4r89g4d6 [609aec21985569] La signature calculée par Mercanet à la réception de la requête n’est pas identique à celle que vous avez envoyée.
  • Lors des tests en simulation, vérifiez la valeur de la clé utilisée avec celle fournie plus loin dans ce document (cf étape 3)
  • Sur le serveur de production, vérifiez la clé utilisée avec celle récupérée sur Mercanet Téléchargement
Version de clé invalide Invalid field value : Unable to find a valid key for the following keyVersion=0 [609aec2b60b1d0] Mercanet ne trouve pas la version de clé que vous indiquez (champ keyVersion).
  • Lors des tests en simulation, vérifiez la version de la clé utilisée avec celle fournie plus loin dans ce document (cf étape 3)
  • Sur le serveur de production, vérifiez la version de la clé utilisée avec celle récupérée sur Mercanet Téléchargement
Champ Encode incorrect Invalid keyword : ENCODE [609aecdee11d52] Vérifiez que l’algorithme de l’encodage que vous utilisez est correctement renseigné dans le champ encode.
URL de retour incorrecte Technical problem : code=30 message=normalReturnUrl is invalid https:// [609aec31b00b94] Vérifiez la syntaxe de l’URL que vous indiquez dans le champ normaReturnUrl
Note: les messages sont affichés sur la plateforme de simulation pour vous aider à valider l’intégration de votre site Web. Pour des raisons de sécurité, des messages d’erreur beaucoup plus simples sont affichés sur la plateforme de production. Ex « Erreur lors du traitement de la requête de paiement. Contactez votre commerçant ».

Une fois le paiement terminé :

  • Mercanet affiche le ticket de caisse
  • Une réponse automatique vous est envoyée à l’URL contenue dans le champ autoResponseUrl de la requête (optionnel mais fortement conseillé).
  • Mercanet invite le client à revenir sur votre site grâce à l’URL renseignée dans le champ normalReturnUrl de la requête. L'action faite par le client déclenche l'envoi d'une réponse manuelle.

Ces quatre champs sont retournés par Mercanet dans les réponses (automatique et manuelle) :

Champs Description
Data Contient les champs de réponse. Respecte la même syntaxe que le champ Data de la requête de paiement.
Encode Type d’encodage utilisé. S’il vaut base64 ou base64url, le champ Data doit être décodé en Base64/Base64Url pour retrouver la chaîne des champs concaténés.
Seal Signature du champ Data qui permet de garantir la sécurité de la réponse de paiement.
InterfaceVersion Valeur et numéro de version de l’interface utilisée.

Tout d’abord vous devez vérifier la sécurité du message retourné en recalculant le Seal selon la même méthode que celle utilisée pour la requête. Ensuite, comparez le champ Seal calculé avec celui de la réponse Mercanet.

Si les Seal sont identiques, vous poursuivez en traitant la réponse de paiement contenue dans le champ Data.

Dans le cas contraire, vous devez stopper le traitement: vérifier la clé secrète et/ou l’algorithme utilisés et si besoin contacter le support technique.

La réponse de paiement contenue dans le champ Data est composée :

  • Champs génériques
Champs Format Description
amount N12 Montant de la transaction. Le montant est transmis dans la plus petite unité de la devise. Exemple pour l’Euro : un montant de 10,50 Euros doit être transmis sous la forme 1050.
currencyCode N3 (restricted value / ISO4217) Code de la devise de la transaction. Ce code est compatible ISO 4217.
customerId AN19 (restrictedString) Identifiant du client
customerEmail ANS128 (email) E-mail du contact
transactionReference AN35 Identifiant unique de la transaction par commerçant.
guaranteeIndicator A1 (restricted values) Niveau de garantie de la transaction (tableau des valeurs ci-dessous).
orderId ANS32 Numéro de commande associé à la transaction de paiement
responseCode N2 (restricted values) Code réponse du serveur Mercanet (tableau des valeurs ci-dessous).
acquirerResponseCode AN2 (restricted values) Code réponse retourné par l’acquéreur lors d’une demande d’autorisation (tableau des valeurs ci-dessous).
authorisationId AN10/ANS32 Identifiant d’autorisation, retourné par le serveur d’autorisation de la banque du client en cas d’accord (non renseigné en cas de refus).
maskedPAN ANS19 Numéro de PAN masqué.
panExpiryDate N6 (YYYYMM) Date d'expiration du PAN.
paymentMeanBrand ANS20 (restricted values) Nom du moyen de paiement utilisé par le client. Valeurs :
  • CB
  • VISA
  • MASTERCARD
  • ELECTRON
  • VPAY
  • MAESTRO
  • PAYPAL
returnContext ANSU255 (extendedString) Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions.
  • Champs si paiement carte
Champs Format Description
holderAuthenStatus ANS20 (restricted values) Résultat du processus d’authentification porteur (tableau des valeurs ci-dessous).
cardProductCode AN5 Code produit de la carte.
cardProductName ANS70 Libellé du code produit de la carte.
issuerCode AN6 Code émetteur de la carte
issuerCountryCode A3 (restricted values) Code pays de l’émetteur de la carte
issuingCountryCode A3 (restricted values) Code pays dans lequel la carte est émise
  • Champs si paiement PayPal

    pas de champ spécifique
  • Valeurs des champs à analyser

Le champ responseCode donne le résultat de l’acceptation.

La valeur 00 dans le champ responseCode signifie que le paiement est accepté.

En cas de refus (responseCode différent de 00), le champ acquirerResponseCode précise la nature du refus de la banque (si paiement carte) ou du serveur PayPal (si paiement PayPal).

responseCode Description Type refus
00 Transaction acceptée
05 Transaction refusée Bancaire
34 Suspicion de fraude (seal erroné) Fraude
75 Nombre maximum de tentatives atteint Moyen de paiement
90 Service temporairement indisponible Technique
97 Session expirée (aucune action de l'utilisateur pendant 15 min), transaction refusée Technique
99 Problème temporaire au niveau du serveur Mercanet Technique
holderAuthentStatus Description Valeur 3-D
ATTEMPT Le client n’a pas eu à s’authentifier. 3D_ATTEMPT
CANCEL Le client a abandonné durant l'authentification. 3D_ABORT
ERROR Problème technique lors de l’authentification 3DS. 3D_ERROR
FAILURE Le client n’a pas réussi à s’authentifier (erreur de mot de passe). 3D_FAILURE
NOT_ENROLLED La carte utilisée n’est pas enrôlée 3-D Secure. 3D_NOTENROLLED
NOT_PARTICIPATING Le client ne s’est pas authentifié car :
  • le type de carte n’est pas supporté par le 3DS ;
  • vous n’êtes pas inscrit au programme 3DS.
SSL
SUCCESS Le porteur de la carte s’est authentifié correctement. 3D_SUCCESS
guaranteeIndicator Description
Y Paiement 3D garanti
N Paiement 3D non garanti
U Garantie 3D non définie
Paiement non 3D
acquirerResponseCode Description Correspondance responseCode
00 Transaction approuvée ou traitée avec succès 00
02 Contacter l'émetteur du moyen de paiement 02
03 Accepteur invalide 03
04 Conserver le support du moyen de paiement 05
05 Ne pas honorer 05
07 Conserver le support du moyen de paiement, conditions spéciales 05
08 Approuver après l'identification 05
12 Transaction invalide 12
13 Montant invalide 05
14 Coordonnées du moyen de paiement invalides 14
15 Émetteur du moyen de paiement inconnu 05
17 Paiement interrompu par le client 17
24 Opération impossible 05
25 Transaction inconnue 05
30 Erreur de format 30
31 Id de l'organisation d'acquisition inconnu 05
33 Moyen de paiement expiré 05
34 Suspicion de fraude 34
40 Fonction non supportée 05
41 Moyen de paiement perdu 05
43 Moyen de paiement volé 34
51 Provision insuffisante ou crédit dépassé 05
54 Moyen de paiement expiré 05
56 Moyen de paiement manquant dans le fichier 05
57 Transaction non autorisée pour ce porteur 05
58 Transaction interdite au terminal 05
59 Suspicion de fraude 05
60 L'accepteur du moyen de paiement doit contacter l'acquéreur 05
61 Excède le maximum autorisé 05
62 Transaction en attente de confirmation de paiement 05
63 Règles de sécurité non respectées 05
65 Nombre de transactions du jour dépassé 05
68 Réponse non parvenue ou reçue trop tard 05
75 Nombre de tentatives de saisie des coordonnées du moyen de paiement dépassé 75
87 Terminal inconnu 05
90 Arrêt momentané du système 90
91 Emetteur du moyen de paiement inaccessible 90
92 La transaction ne contient pas les informations suffisantes pour être redirigée vers l'organisme d'autorisation Transaction dupliquée 90
94 Transaction dupliquée 90
96 Mauvais fonctionnement du système 90
97 Requête expirée: transaction refusée 90
98 Serveur inaccessible 90
99 Incident technique 99
A1 Paiement refusé par l'acquéreur (données 3-D Secure manquantes dans la demande d'autorisation). 05
Etat Champs de la réponse Action à réaliser
Paiement 3-D Secure 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 3-D Secure

reponseCode = 05

holderAuthenStatus = FAILURE

L’authentification du client 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 responseCode = 05 L’autorisation est refusée pour un motif non lié à la fraude. Vous pouvez proposer à votre client de payer avec un autre moyen de paiement en générant une nouvelle requête.
Repli VADS

responseCode = 05

acquirerResponseCode = A1

Le paiement a été refusé par l'acquéreur car il manque les données 3-D Secure dans la demande d'autorisation.
Veuillez retenter le paiement avec une cinématique 3-D Secure.
Refus fraude responseCode = 34 Autorisation refusée pour cause de fraude. Ne livrez pas la commande.
Refus nombre max d’essais atteint responseCode = 75 Le client a fait plusieurs tentatives toutes échouées car les informations saisies n’étaient pas correctes. Deux possibilités :
  • Difficulté pour votre client à renseigner les informations carte
  • Tentative de carding (recherches de numéros de cartes possibles)
Prenez contact avec votre client pour définir avec lui 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.

Une fois le développement de la connexion à Mercanet réalisé, vous pouvez effectuer un test sur le serveur Mercanet de recette :

Url :

Pour effectuer vos tests, utilisez la boutique et recette ainsi que les cartes mentionnées sur cette page :

merchantId 211000021310001
scretKey S9i8qClCnb2CZU3y3Vn0toIOgz3z_aBi79akR30vM9o
keyVersion 1
Attention:

Cette boutique de test accepte uniquement la devise Euro.

Une fois la connexion de votre site Web à testée, vous êtes à présent en mesure de valider la connexion à Mercanet Paypage POST de production.

Pour ce faire, vous devez changer l’URL pour vous connecter au serveur Mercanet de production en utilisant les identifiants reçus lors l’inscription (merchantId, secretKey et keyVersion).

URL https://payment-webinit.mercanet.bnpparibas.net/paymentInit
merchantId Identifiant de la boutique reçu par mail
secretKey Clé secrète que vous récupérez via Mercanet Téléchargement
keyVersion Version clé secrète récupérée sur Mercanet Téléchargement (logiquement 1 pour la 1ère clé)
Attention: une erreur fréquente est d’oublier un de ces quatre paramètres ce qui conduit systématiquement à une erreur.

Au préalable, nous conseillons d’isoler votre site Web du public pour éviter que des clients effectuent des transactions pendant cette phase de validation.

Immédiatement :

  • faites une transaction avec une carte de paiement réelle (si possible la vôtre). Si la transaction est acceptée, elle sera envoyée en banque pour créditer votre compte commerçant et débiter le compte carte ;
  • vérifiez que vos pages de paiement intègrent vos paramètres de personnalisation ;
  • consultez la transaction via Mercanet Back Office à partir du transactionReference.

Le lendemain :

  • vérifiez la présence de la transaction dans le journal des transactions ;
  • vérifiez sur votre compte que l’opération a bien été créditée ;
  • remboursez la transaction via Mercanet Back Office (optionnel).

Le surlendemain :

  • vérifiez que l’opération de remboursement apparaît dans le journal des opérations ;
  • vérifiez sur votre compte le débit suite au remboursement.

Cette procédure de validation est également applicable au moyen de paiement PayPal.

Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’acheter et de payer.

Dans la journée :

  • surveillez le taux d’acceptation (nombre de responseCode 00 / nombre total de transactions).
  • vérifiez la nature des refus non bancaires :
    • problème technique : responseCode 90, 99 ;
    • fraude : responseCode 34 ;
    • nombre maximum de tentatives de paiement atteint : responseCode 75 ;
    • abandon : responseCode 97.

Le lendemain :

  • vérifiez dans le journal des transactions la présence de toutes les transactions traitées (acceptées et refusées) ;
  • vérifiez, dans le journal des opérations, les opérations que vous avez effectuées ainsi que les remises (si vous avez choisi cette option du journal).

Afin d'utiliser le moyen de paiement PayPal sur votre site Web, vous devez posséder un compte PayPal. Il doit s'agir d'un compte professionnel (le type du compte est choisi lorsque vous vous enregistrez sur http://www.PayPal.com).

Si vous avez plusieurs boutiques actives, nous vous suggérons de créer un compte PayPal pour chacune.

Sur votre compte PayPal, vous devez, en tant que commerçant, autoriser le prestataire de services de paiement (PSP) à appeler l'API de PayPal.

Attention: les captures des pages PayPal sont données ici à titre indicatif. Il se peut que PayPal modifie ses pages.

Dans votre compte d'entreprise PayPal, allez dans Paramètres du compte, puis Accès à l'API :


screenshot de l'écran PayPal : cliquez sur mettre à jour à côté d'accès API

Cliquez sur le lien Solution de paiement pré-intégrée.



La fenêtre Ajouter de nouveaux droits d'accès à un tiers s'ouvre. Dans le champ textuel, entrez le compte technique Mercanet sips-gestion-services_api1.worldline.com puis cliquez sur Rechercher.

Sélectionnez les options suivantes :

  • Utiliser Express Checkout pour traiter les paiements ;
  • Émettre un remboursement pour une transaction spécifique ;
  • Traiter les paiements par carte bancaire de vos clients;
  • Autoriser et collecter vos transactions PayPal ;
  • Obtenir des informations concernant une transaction en particulier ;
  • Rechercher dans vos transactions les éléments correspondant à des critères spécifiques ;
  • Obtenir une autorisation pour les paiements préapprouvés et initier des transactions préapprouvées ;
  • Utiliser Express Checkout pour traiter les paiements par mobiles.

Cliquez ensuite sur le bouton Ajouter.



Attention:

Si vous souhaitez dupliquer des transactions, vous devez également sélectionner l'option "Débiter un client sur la base d'une transaction antérieure".

Afin d'accéder à l'interface Mercanet Téléchargement, vous devez au préalable vous connecter au portail Merchant Extranet via l'URL : https://acces-merchant.mercanet.bnpparibas.net/portal/home avec l'identifiant qui vous a été retourné par Mercanet lors de l’inscription de votre boutique .


Image de l'écran d'accueil de l'extranet commerçant.

Si vous avez un utilisateur permettant d'accéder à plusieurs boutiques, l'onglet "Téléchargement" permettant d'accéder à Mercanet Téléchargement est grisé. Pour l'activer, vous devez sélectionner une boutique.

Ensuite allez dans l’onglet "Téléchargement" puis "Gestion des clés" :


image montrant la page de gestion des clés

Vous pouvez télécharger votre clé secrète :


Capture d'écran montrant l'icône "téléchargement".

La solution Mercanet est conforme à la règlementation en vigueur définie par CB, Visa et Mastercard.

PCI DSS est un standard de sécurité international dont les objectifs sont d’assurer la confidentialité et l’intégrité des données des porteurs de cartes, et ainsi de sécuriser la protection des données carte et des transactions. Vous et les prestataires de paiement sont tenus de s’y conformer, à des degrés divers en fonction de l’importance de leur activité. La solution Mercanet est certifiée PCI DSS depuis 2006.

En utilisant Paypage, vous n’avez pas accès aux données du porteur de carte et n’avez pas besoin d’être certifié PCI DSS. Les données carte sont gérées par BNP Paribas.

La solution Mercanet 2.0 est soumise à la réglementation européenne MIF (JO EU 2015/751 L123 du 19/05/2015). Parmi ces règles, la « sélection de la marque » vous impose de proposer au client porteur d’une carte cobadgée le choix de la marque au moment du paiement, ce qui impacte la page de paiement.

Une carte cobadgée est une carte qui supporte au moins deux marques. La plupart des cartes émises en France sont cobadgées avec CB (carte CB/VISA, CB/MASTERCARD, CB/MAESTRO…).

Ainsi vous devez laisser le choix de la marque au client porteur de ces cartes cobadgées. À titre d’illustration, l’écran ci-dessous présente un exemple de carte cobadgée CB + Visa avec CB en marque par défaut. Le client peut changer la marque en cliquant sur le lien en bas de l’écran.



Note: pour les cartes non cobadgées, aucun choix de marque n’est proposé.

Si vous souhaitez implémenter d’autres moyens de paiement ou options, veuillez-vous référer aux documentations associées.

Cette liste n’est pas exhaustive mais vous présente les documents complémentaires pour vous aider à aller plus loin dans la mise en œuvre de Mercanet.

Guide Pourquoi le lire ?
Dictionnaire des données Ce guide vous permet de connaître la définition et l’ensemble de valeurs des champs des connecteurs et journaux.
Présentation fonctionnelle Ce guide vous permet d’avoir une vue d’ensemble des fonctionnalités de Mercanet et des options disponibles auxquelles vous pouvez souscrire.
Guide de configuration des fonctionnalités Ce guide vous explique la mise en œuvre des fonctionnalités Mercanet.
Description des journaux Ce guide décrit le contenu des journaux envoyés par Mercanet.
Personnalisation de Paypage pour les boutiques Ce guide vous explique comment personnaliser les pages de paiement afin qu’elles aient une charte graphique similaire au reste de votre site.
OneClick Ce guide décrit la solution OneClick qui permet à vos clients de payer en un clic sans avoir à ressaisir leurs données cartes.
Mercanet Message Ce guide explique comment implémenter la solution Mercanet message qui vous permet d’envoyer à vos clients une notification de paiement par mail ou par SMS .
Mercanet Téléchargement Ce guide explique comment télécharger la documentation et votre clé secrète via l’extranet Mercanet Téléchargement.
Mercanet Back Office Ce guide décrit l’ensemble des actions de gestion de caisse que vous pouvez effectuer via Mercanet Back Office.
Gestion de la lutte contre la fraude – Go-no-Go Ce guide explique le fonctionnement, la configuration et l’utilisation du moteur de lutte contre la fraude Go-No-Go. Il vous permet de définir les règles d’acceptation fraude que vous souhaitez mettre en place lors du paiement.
Paypage POST Ce guide décrit et explique comment implémenter l’intégralité des options du connecteur .
Intégration American Express Ce guide vous explique comment intégrer les cartes American Express.
Retourner en haut de page Besoin d'aide ?

Besoin d'aide ?

Fermer