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-success   URL vers laquelle le formulaire est soumis (methode POST) en cas de succès.
kr-get-url-success   URL vers laquelle le formulaire est soumis (methode POST) en cas de succès.
kr-post-url-refused   URL appelée lorsque toutes les tentatives ont échoué (methode POST).
kr-get-url-refused   URL appelée lorsque toutes les tentatives ont échoué (methode GET).
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).
kr-placeholder-identity-document-type   Placeholder du champ du type de document d’identité si requis (cas LATAM)
kr-placeholder-identity-document-number   Placeholder du champ du numéro de document d’identité si requis (cas LATAM)
kr-placeholder-card-holder-mail   Placeholder du champ email si requis (cas LATAM)
kr-placeholder-card-holder-name   Placeholder du champ du nom du porteur si requis (cas LATAM)
kr-spa-mode   if true, form is not automatically initialized. (default is false)

Ces paramètres peuvent également être surchargés avec la méthode KR.setFormConfig(). Par exemple, pour surcharger le paramètre kr-post-url-success:

KR.setFormConfig({'kr-post-url-success': 'https://my.site'}).then( ({KR}) => {
    /* there is no errors */
);

Attention, si les paramètres kr-post-url-success et kr-post-url-success sont défini en même temps, la méthode POST aura la priorité. Il en va de même pour kr-post-url-refused et kr-get-url-refused*.

É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.button.onClick() Appelé lorsque l’acheteur clique sur le bouton du formulaire.

Tous les événements retournent des promesses, vous permettant de les intégrer dans une chaine. Voir Travailler dans un environement asynchrone pour plus d’informations.

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 :

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
true le client JavaScript effectue un POST sur kr-post-success-url.
false Le POST sur kr-post-success-url n’est pas effectué. Vous gérez vous-même l’action post-paiement.

KR.button.onClick()

KR.button.onClick() permet d’effectuer des traitements personnalisés avant que le client JavaScript valide le formulaire et effectue l’appel pour créer une transaction.

Il vous est possible d’arrêter la chaine d’exécution en retournant false à la fin du traitement:

Valeur de retour Comportement
false l’exécution est interrompue. La gestion d’erreur n’a pas lieu. La transaction n’est pas créée.
 true l’exécution continue normalement lorsque la callback est executée.

Méthodes

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

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

Tous les événements retournent des promesses, vous permettant dans les intégrer dans une chaine. Voir Travailler dans un environement asynchrone pour plus d’informations.

Voir la documentation de KR.validateForm() pour plus de details.

KR.setFormConfig()

Cette méthode permet de surcharger les paramètres d’initialisation, mais également 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’erreur.

Cette methode retourne une promesse (promise).

KR.validateForm()

Cette méthode vérifie localement si le formulaire est valide. Elle retourne une promesse:

  • then() est appelé quand le formulaire est valide. result sera valorisé à null.
  • catch() est appelé lorsque le formulaire est invalide. result contient le détail de l’erreur.

Exemple d’appel:

KR.validateForm().then( ({KR, result}) => {
    /* there is no errors */
    /* result == null */
    }
)
.catch( ({KR, result}) => {
    /* Get the error message */
    var code = result.errorCode;
    var message = result.errorMessage;
    var myMessage = code + ": " + message;
    console.log(myMessage);

    /* if you have defined a callback using      */
    /* result.onError(), you can trigger it calling: */
    return result.doOnError();
    }
);

Une fois que vous avez intercepté les erreurs, vous pouvez déclancher l’événement KR.onError() manuellement en appelant result.doOnError();.

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’animation 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 effectura automatiquement le remplacement :

Utilisation avancée

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