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:

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.custom.fields.php#L75-L97

  <!-- 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 champ 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:

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.custom.fields.php#L79-L85

   <!-- 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ées

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

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.custom.fields.php#L79-L85

   <!-- 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 de votre page:

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.custom.fields.php#L68-L71

  <!-- 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>