Ajouter des champs personnalisés à votre formulaire

Pour insérer un champ personnalisé au formulaire de paiement, il suffit d’ajouter les balises HTML standards dans la div kr-embedded:

  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

   <!-- custom text field -->
   <input type="text"
          name="acme-email"
          placeholder="email"
          class="kr-theme"
          kr-icon="fas fa-envelope"
          required/>

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

    <!-- custom checkbox field -->
    <input type='checkbox'
           name='acme-terms'
           label="add me to your mailing list" 
           class="kr-theme"
           required/>

    <!-- custom hidden field -->
    <input type='hidden'
           name='acme-hidden'
           value='my hidden value'/>

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

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

Cet exemple de code va insérer:

  • un champ email obligatoire comme 1er champ du formulaire
  • une case à cocher obligatoire à la fin du formulaire
  • un champs caché

Lorsque le paiement est effectué, ces champs personnalisés seront ajoutés dans les paramètres POST transmis au marchand :

{
  "kr-hash": "a8bbe12b1562696677a2bd93ce04d676e4aba47e538cb97abb8b8ad2b418cb08",
  "kr-hash-algorithm": "sha256_hmac",
  "kr-answer-type": "V4\/Payment",
  "kr-answer": "{...}",
  "acme-email": "hello@email.acme",
  "acme-terms": "true",
  "acme-hidden": "my hidden value"
}

Validation HTML5

Vous pouvez ajouter les directives de validation HTML5 à votre champ personnalisé:

Les erreurs de validation sont traitées de la même façon que les erreurs des champs de formulaire:

  • les validations seront appliquées localement,
  • les erreurs seront affichées dans la zone d’erreur du formulaire,
  • la callback de gestion d’erreur définie à partir de KR.onError() est prise en charge,
  • le thème sera appliqué automatiquement.

A ce jour, les directives HTML5 supportées sont:

Directive Description
required Le champ est obligatoire.

Lorsqu’un champ obligatoire est envoyé à vide, la librairie JavaScript lève une erreur de type CLIENT_304.

Thèmes et CSS

Les champs additionnels utilisent les CSS par défaut de votre site. Il est possible d’appliquer automatiquement le thème du formulaire de paiement en ajoutant la classe kr-theme à l’élément:

   <!-- custom text field -->
   <input type="text"
          name="acme-email"
          placeholder="email"
          class="kr-theme"
          kr-icon="fas fa-envelope"
          required/>

L’ajout de kr-theme permet d’appliquer automatiquement:

  • le thème courant du formulaire de paiement
  • la gestion des erreurs (annimations, couleurs) sur le champ.

Icônes personnalisés

Vous pouvez ajouter des icônes personnalisées dans les champs additionnels grâce au paramètre kr-icon:

   <!-- custom text field -->
   <input type="text"
          name="acme-email"
          placeholder="email"
          class="kr-theme"
          kr-icon="fas fa-envelope"
          required/>

Les icônes de Font-Awesome sont aussi supportées. Vous devez au préalable charger la librairie dans la section <head> de votre page:

  <!-- include font awesome for custom fields icons -->
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css"
        integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt"
        crossorigin="anonymous">

D’autres librairies seront ajoutées dans les futures releases.

Tabulation

Vous pouvez également contrôler l’ordre des tabulations en ajoutant le paramètre kr-tab-order:

<div class="kr-embedded"
        kr-form-token="<?php echo $formToken;?>">

        <!-- custom fields -->
        <input type="text"
                name="acme-email"
                placeholder="email"
                class="kr-theme"
                kr-icon="fas fa-envelope"
                kr-tab-order="1"
                required/>

        <!-- payment form fields -->
        <div class="kr-pan" kr-tab-order="2"></div>
        <div class="kr-expiry" kr-tab-order="3"></div>
        <div class="kr-security-code" kr-tab-order="4"></div>

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

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

Ce paramètre n’est nécessaire que lorsqu’un champ additionel est présent.

Valeur par défaut

Vous pouvez également définir la valeur par défaut en ajoutant l’attribut html value:

<div class="kr-embedded"
        kr-form-token="<?php echo $formToken;?>">

        <!-- custom fields -->
        <input type="text"
                name="acme-email"
                placeholder="email"
                class="kr-theme"
                kr-icon="fas fa-envelope"
                value="mail@example.com"
                required/>

        <!-- payment form fields -->
        <div class="kr-pan" kr-tab-order="2"></div>
        <div class="kr-expiry" kr-tab-order="3"></div>
        <div class="kr-security-code" kr-tab-order="4"></div>

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

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