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