Référence du client JavaScript

Le client JavaScript permet de créer un formulaire de paiement sur votre site marchand, grâce au code suivant :

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.payzen.eu/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://api.payzen.eu/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://api.payzen.eu/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded" 
   kr-form-token="ff:d433b3eee93b40cbac0a20efd13bfccc:161018165424:000003de45555201:9e:01">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>  

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>  
</body>
</html>

Rendez-vous ici pour une documentation complète :  Démarrer: Paiement simple

Paramètres d’initialisation

Différents paramètres peuvent être définis au chargement du client JavaScript. Par exemple, pour définir kr-public-key et kr-post-url-success :

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.payzen.eu/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>
  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

Les paramètres disponibles sont les suivants :

Paramètre Requis Description
kr-public-key oui Clé publique à utiliser pour réaliser le paiement.
kr-language   Langue d’affichage du formulaire au format Culture (fr-FR).
kr-post-url-refused   URL appelée lorsque toutes les tentatives ont échoué.
kr-post-url-success   URL vers laquelle le formulaire est POSTé en cas de succès.
kr-clear-on-error   Désactive l’effacement du CVV en cas de transaction refusée (true ou false).
kr-hide-debug-toolbar   Cache la barre de debug en mode test (true ou false).
kr-placeholder-expiry   Placeholder du champ kr-expiry (date d’expiration).
kr-placeholder-pan   Placeholder du champ kr-pan (numéro de carte).
kr-placeholder-security-code   Placeholder du champ kr-security-code (CVV).

Événements

Il est possible d’attacher des callbacks JavaScript personnalisés à divers événements. Le client JavaScript supporte les événements suivants :

Paramètre Description
KR.onError() Permet d’être notifié lorsqu’une erreur se produit.
KR.onFocus() Un des champs du formulaire a le focus.
KR.onFormCreated() Le formulaire de paiement est prêt mais le contenu des iframes n’est pas encore chargé.
KR.onFormReady() Le formulaire est prêt à être utilisé.
KR.onLoaded() Premier évenement appelé avant la création du formulaire.
KR.onSubmit() Appelé juste avant que le formulaire soit POSTé.

KR.onError()

KR.onError() permet d’intercepter les erreurs avant qu’elles ne soient affichées.

Exemple d’interception des messages d’erreurs :

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onError( function(event) {
            var code = event.errorCode;
            var message = event.errorMessage;
            var myMessage = code + ": " + message;

            $("#customerror").html(myMessage);
          });
    });
  </script>

Ensuite, les messages d’erreurs seront automatiquement affichés dans l’élément suivant, s’il est présent :

    <!-- error zone -->
    <div class="kr-form-error"></div>
    <!-- error zone -->
    <div class="kr-form-error"></div>

Lorsque plusieurs erreurs sont génerées, elles sont regroupées au sein d’une erreur unique. La propriété children contiendra le détail de toutes les erreurs :

{
    "errorCode": "CLIENT_300",
    "errorMessage": "Invalid form data",
    "children": [{
        "errorCode": "CLIENT_301",
        "errorMessage": "Invalid card number",
        "field": "pan",
        (...)
    }, {
        "errorCode": "CLIENT_302",
        "errorMessage": "Invalid expiry date",
        "field": "expiryDate",
        (...)
    }, {
        "errorCode": "CLIENT_303",
        "errorMessage": "Invalid security code",
        "field": "securityCode",
        (...)
    }],
    "detailedErrorCode": null,
    "detailedErrorMessage": null,
    (...)
}

Pour plus de détails sur les erreurs, rendez-vous ici :  Gérer les erreurs (client JS)

KR.onFocus()

KR.onFocus() permet d’être notifié lorsqu’un champ du formulaire prend le focus :

Exemple d’intégration :

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onFocus( function(event) {
            var myMessage = "focus on: " + event.field;

            $("#custommessage").html(myMessage);
          });
    });
  </script>

Si le champ du numéro de carte prend le focus, la variable event prendra la valeur suivante :

{
    "field":"pan",
    "formId":"F73867",
    "_type":"krypton/focus"
}

KR.onSubmit()

KR.onSubmit() permet d’intercepter les informations sur la transaction autorisée avant que le formulaire n’effectue un POST sur l’URL définie avec kr-post-success-url.

Exemple d’intégration :

  <script type="text/javascript">
    $(document).ready(function() {
      KR.onSubmit( function(event) {
        /* Change the button label to the orderStatus */
        $(".kr-payment-button > span:first").html(event.clientAnswer.orderStatus);
        $(".kr-spinner").hide();
        $(".kr-payment-button > span:first").show();
        
        /* return values:
         * true: kr-post-success-url is called using POST
         * false: kr-post-success-url is not called, execution stops.
         */
        return false;
      });
    });
  </script>

L’objet contenu dans event est le même que celui POSTé par le formulaire. Pour plus de détails, rendez-vous ici : Retour navigateur.

Le comportement diffère en fonction du booléen retourné par votre fonction :

Valeur de retour Comportement
false Comportement par défaut : le client JavaScript effectue un POST sur kr-post-success-url.
 true Le post sur kr-post-success-url n’est pas effectué. Vous gérez vous-même l’action post-paiement.

Méthodes

Plusieurs méthodes sont à votre disposition pour interagir avec le client JavaScript :

Paramètre Description
KR.setFormConfig() Permet de modifier à chaud la configuration du client JavaScript, voir la section suivante.
KR.setFormToken() Raccourci permettant de changer le formToken du formulaire courant.
KR.validateForm() Déclenche la validation locale du formulaire.
KR.setShopName() Change le nom de la boutique définie dans l’entête de la pop-in.

Toutes ces méthodes retournent des promesses.

KR.setFormConfig()

cette fonction permet de changer à chaud les éléments suivants :

Utilisation Description
KR.setFormConfig({formToken: “NEW_FORM_TOKEN”}); Change le formToken courant.
KR.setFormConfig({language: “fr-FR”}); Change la langue du formulaire de paiement et des messages d’erreurs.

Cette methode retourne une promesse (promise).

Personnalisation du bouton

Le bouton de paiement est automatiquement ajouté dans votre formulaire à partir du code suivant :

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>
    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

Il y a de multiples avantages à utiliser notre bouton de paiement :

  • Les labels sont traduits automatiquement
  • Le montant est automatiquement formaté et mis à jour
  • Nous gérons pour vous l’annimation d’attente
  • Le bouton passe automatiquement en read-only si nécessaire

Si vous souhaitez gérer vous-même le label du bouton, il suffit de l’ajouter de la façon suivante :

Vous pouvez également insérer une variable qui représente le montant et la devise. Le client javascript éfféctura automatiquement le remplacement :

Utilisation avancée

Pour voir tous les cas d’utilisation avancés, rendez-vous sur Fonctionnalités du client JavaScript.