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 :
Rendez-vous ici pour une documentation complète : Démarrer: Paiement simple
Plateformes supportées
Nous faisons tout notre possible pour supporter toutes les versions récentes des principaux navigateurs disponibles sur le marché.
Pour des raisons de sécurité et pour délivrer la meilleure expérience utilisateur à la majorité de nos marchands, nous ne supportons pas les navigateurs et les systèmes d'exploitation qui ne reçoivent plus de patch de sécurité.
Ces navigateurs représentent une infime minorité du trafic effectuant des paiements sur Internet.
Nous supportons :
- Internet Explorer à partir de sa version 10
- Edge à partir de sa version 17
- Chrome à partir de sa version 70
- Firefox à partir de sa version 64
- Safari (Desktop et mobile) à partir de sa version 11
- Android native browser à partir d'Android 5.0
- toutes les dernières versions d'IOS à partir de l'iphone 4S.
TLS 1.2 doit être supporté par le navigateur.
Nous testons de façon proactive la plupart des navigateurs, aussi bien sur mobile que sur desktop. Mais il est possible qu'une combinaison de mobile + navigateur échappe à notre vigilance. Dans ce cas, veuillez contacter notre support.
Si vous souhaitez supporter une combinaison qui n'est pas prise en compte par notre client JavaScript, vous pouvez dans ce cas de figure implémenter notre formulaire en redirection.
Notez également que certains antivirus ou ad-blocker peuvent potentiellement bloquer notre solution. Merci de contacter le support si vous constatez toute détection abusive.
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 :
Les paramètres disponibles sont les suivants :
Paramètres généraux:
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 (méthode POST) en cas de succès. | |
kr-get-url-success | URL vers laquelle le formulaire est soumis (méthode GET) en cas de succès. | |
kr-post-url-refused | URL appelée lorsque toutes les tentatives ont échoué (méthode POST). | |
kr-get-url-refused | URL appelée lorsque toutes les tentatives ont échoué (méthode 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-spa-mode | Si la valeur est true, le formulaire n'est pas automatiquement initialisé (false est la valeur par défaut). |
Classes à utiliser pour la personalisation des champs :
Paramètre | Description |
---|---|
kr-pan | Numéro de la carte |
kr-expiry | Date d'expiration |
kr-security-code | Code de sécurité (cvv) |
kr-installment-number | Nombre d'échéances (champ spécifique à l'Amérique Latine) |
kr-first-installment-delay | Nombre de mois de différé à appliquer sur la première échéance (champ spécifique à l'Amérique Latine) |
kr-identity-document-type | Type de document d'identité (champ spécifique à l'Amérique Latine) |
kr-identity-document-number | Numéro de la pièce d'identité (champ spécifique à l'Amérique Latine) |
kr-card-holder-name | Nom du porteur de la carte (champ spécifique à l'Amérique Latine) |
kr-card-holder-mail | Adresse e-mail du porteur de la carte (champ spécifique à l'Amérique Latine) |
kr-do-register | la case à cocher de confirmation de creation de token de carte |
Paramètre | Requis | Description |
---|---|---|
kr-placeholder-expiry | Placeholder du champ kr-expiry (date d'expiration). |
Classes à utiliser pour la personalisation des "place holders" :
Paramètre | Requis | Description | cas LATAM |
---|---|---|---|
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 | oui | |
kr-placeholder-identity-document-number | Placeholder du champ du numéro de document d'identité si requis | oui | |
kr-placeholder-installments-default | Placeholder du champ Mode de paiement par défaut | ||
kr-placeholder-installments-single-payment | Placeholder du champ Mode de paiement quand il y en a qu'un | ||
kr-placeholder-installments-single-payment-credit | Placeholder du champ Mode de paiement quand il y en a que du crédit | ||
kr-placeholder-first-installment-delay | Placeholder du champ Délai de paiement | oui | |
kr-placeholder-card-holder-mail | Placeholder du champ email si requis | oui | |
kr-placeholder-card-holder-name | Placeholder du champ du nom du porteur si requis | oui |
Classes à utiliser pour la personalisation des labels animés (spécifique au thème material) :
Paramètre | Requis | Description | Template | cas LATAM |
---|---|---|---|---|
kr-label-expiry | Label animé du champ kr-expiry (date d'expiration). | |||
kr-label-pan | Label animé du champ kr-pan (numéro de carte). | |||
kr-label-security-code | Label animé du champ kr-security-code (CVV). | |||
kr-label-identity-document-type | Label animé du champ du type de document d'identité si requis | oui | ||
kr-label-identity-document-number | Label animé du champ du numéro de document d'identité si requis | oui | ||
kr-label-card-holder-mail | Label animé du champ email si requis | oui | ||
kr-label-card-holder-name | Label animé du champ du nom du porteur si requis | oui | ||
kr-installments-label-singular | Label animé du champ Mode de paiement quand il y en a qu'un | Mon Label [COUNT] avec [CURRENCY] [AMOUNT] | ||
kr-installments-label-plural | Label animé du champ Mode de paiement quand il y en a plusieurs | Mon Label [COUNT] avec [CURRENCY] [AMOUNT] | ||
kr-first-installment-delay-label-plural | Label animé du champ Délai de paiement quand il y en a qu'un | Mon Label [COUNT] | oui | |
kr-first-installment-delay-label-without | Label animé du champ Délai de paiement quand il y en a plusieurs | Mon Label [COUNT] | oui |
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 error */
);
Attention, si les paramètres kr-post-url-success et kr-get-url-success sont définis 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.onBlur() | Un des champs du formulaire perd le focus. voir KR.onFocus() |
KR.onBrandChanged() | Appelé lorsque la marque de la carte a été détectée |
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.onFormValid() | Appelé lorsque la marque de la carte a été détectée |
KR.onInstallmentChanged() | Appelé lorsque l'acheteur sélectionne le nombre d'échéance à appliquer au paiement. |
KR.onLoaded() | Premier événement appelé avant la création du formulaire. |
KR.onPopinClosed() | Emet un evenement lorsque la popIn du formulaire est fermée |
KR.onSubmit() | Appelé juste avant que le formulaire soit posté. |
KR.wallet.onTabChange() | Detecte le changement de tabulation dans le cas du wallet (voir Gestion des wallets acheteur ) |
KR.onTransactionCreated() | Appelé lorsqu'une transaction est créée (acceptée ou refusée) |
KR.button.onClick() | Appelé lorsque l'acheteur clique sur le bouton du formulaire. |
KR.on3dSecureAbort() | Appelé quand l'authentification 3DS est abandonnée par l'utilisateur |
Les événements suivants sont obsolètes et ne sont plus supportés. Ils ne doivent pas être utilisés:
- KR.onFormReadyListener()
- KR.onFormCreateListener()
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.onBrandChanged()
La callback définie dans KR.onBrandChanged() est appelée à chaque fois qu'une marque de carte est detectée. Exemple d'intégration
L'objet cardInfo contient la propriété brand qui peut prendre les valeurs suivantes:
- amex
- cb
- mastercard
- maestro
- visa_electron
- visa
Il contient également le bin de la carte saisie, soit les 6 premiers caractères du pan.
Pour voir la liste complète, consulter la documentation de référence du paramètre effectiveBrand ici: Payment
KR.onFormValid()
La callback définie dans KR.onFormValid() est appelée une fois que tout les champs requis sont remplis et que les données sont valides. Exemple d'intégration
L'objet cardInfo contient la propriété brand qui peut prendre les valeurs suivantes:
- amex
- cb
- mastercard
- maestro
- visa_electron
- visa
Il contient également le bin de la carte saisie, soit les 6 premiers caractères du pan.
Pour voir la liste complète, consulter la documentation de référence du paramètre effectiveBrand ici: Payment
KR.onError()
KR.onError() permet d'intercepter les erreurs avant qu'elles ne soient affichées.
Exemple d'interception des messages d'erreurs :
Ensuite, les messages d'erreurs seront automatiquement affichés dans l'élément suivant, s'il est présent :
<div id="customerror"></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 :
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" }
Vous pouvez aussi utiliser KR.onBlur() pour détecter la perte de focus d'un champ. Son fonctionnement est similiare à KR.onFocus()
KR.onInstallmentChanged()
KR.onInstallmentChanged() permet d'être notifié lorsque l'acheteur sélectionne le nombre d'échéances.
<script type="text/javascript">
$(document).ready(function(){
KR.onInstallmentChanged( function({KR, installmentInfo}){
console.log(installmentInfo)
});
});
</script>
L'objet installmentInfo possède les attributs ci-dessous :
- brand => Marque de la carte. Exemple : "VISA"
- hasInterests => Booléen indiquant si un taux d'intérêt s'applique. Exemple : false
- installmentCount => Nombre total d'échéances. Exemple : 1
- totalAmount => Montant total, intérêt inclus. Exemple : 20000
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 :
La callback reçoit un object avec 2 paramètes :
- KR : Référence à la librairie
- event : Object qui contient la transaction nouvellement créée.
L'objet contenu dans event est le même que celui posté par le formulaire. Pour plus de détails, rendez-vous ici : retour à la boutique.
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.KR.button.onClick() accepte en paramètre soit un callback, soit une promesse (Promise).
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 exécutée. |
KR.onTransactionCreated()
Il exsite 2 callbacks qui permettent d'intercepter une transaction nouvellement créée :
- KR.onSubmit() : Lorsque une transaction acceptée est créée.
- KR.onError() : Lorsque une transaction refusée est créée.
KR.onTransactionCreated() permet d'intercepter toutes les transactions nouvellement créées, qu'elles soient acceptées ou refusées. KR.onTransactionCreated() accepte en paramètre soit un callback, soit une promesse (Promise).
La callback reçoit un object avec 2 paramètes :
- KR : Référence à la librairie
- event : Object qui contient la transaction nouvellement créée.
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, ou la redirection n'a pas lieu. |
true | l'exécution continue normalement lorsque la callback est executée. |
KR.on3dSecureAbort()
Lors de l'authentification 3D-Secure, l'utilisateur peut choisir d'annuler. Cela va engendrer la fermeture de la popIn 3D-Secure et une erreur d'abandon. Cet événement permet d'intercepter l'abanbon de utilisateur.
Notez que dans ce cas, la transaction n'est pas créée en temps réél. Une transaction refusée avec une erreur 149 sera créée de façon asynchrone, et ceci uniquement si l'utilisateur n'a pas effectué une nouvelle tentative de paiement. La création interviendra au bout de 10 minutes maximum. Pour intercepter cette transaction, vous devez utiliser les IPNs. Voir Généralités sur IPN pour plus de détails.
Méthodes
Plusieurs méthodes sont à votre disposition pour interagir avec le client JavaScript :
Méthode | Description |
---|---|
KR.field.focus() | Donne le focus à un champ du formulaire embarqué |
KR.setFormConfig() | Permet de surcharger la configuration du client JavaScript, voir la section suivante. |
KR.setFormToken() | Raccourci permettant de changer le formToken du formulaire actuel. |
KR.setBrand() | Force la détection du moyen de paiement. |
KR.submit() | Soumet le formulaire(). Équivalent au clic utilisateur sur le bouton du formulaire |
KR.validate() | Obsolète, utiliser KR.validateForm() |
KR.validateForm() | Déclenche la validation locale du formulaire. |
Les méthodes suivantes sont obsolètes et ne sont plus supportées. Elles ne doivent pas être utilisées:
- KR.validate(): utiliser KR.validateForm()
- KR.registerPlugin()
Gestion de l'affichage en mode PopIn
Methode | Description |
---|---|
KR.closePopin() | Ferme la popIn (si ouverte) |
KR.openPopin() | Ouvre la popIn (si fermée) |
KR.setShopName() | Change le nom de la boutique définie dans l'en-tête de la pop-in. |
Gestion dynamique du formulaire (Ajout, retrait du DOM):
Methode | Description |
---|---|
KR.addForm(CSS class or id) | Ajoute un formulaire dans un élément du DOM. Retourne un formId |
KR.attachForm(CSS class or id) | Active le formulaire sur un DOM existant. Retourne un formId |
KR.hideForm(formId) | Cache le formulaire |
KR.removeEventCallbacks() | Supprime toutes les callbacks précédemment attachées à l'aide des fonctions KR.on[*] |
KR.removeForms() | Supprime tous les formulaires du DOM (appelle automatiquement KR.removeEventCallbacks()) |
KR.showForm(formId) | Affiche le formulaire |
vous pouvez consulter le dépôt github de Embedded Form Glue pour plus d'informations.
Manipulation du bouton de soumission du formulaire de paiement :
Paramètre | Description |
---|---|
KR.button.setLabel('MON LABEL %amount-and-currency% ') | Définit un label ou %amount-and-currency% sera remplacé par le montant et la devise |
KR.button.showSpinner() | Affiche l'animation d'attente |
KR.button.hideSpinner() | Cache l'animation d'attente |
KR.button.disable() | Désactive le bouton (non clickable) |
KR.button.enable() | Active le bouton |
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.
KR.field.focus()
Pour donner le focus à un champ du formulaire, vous pouvez utiliser la methode KR.field.focus(FIELD_CLASS) Vous devez passer en paramètre la classe du champ du formulaire embarqué.
Par exemple, pour ajouter un bouton qui va donner le focus au champ date d'expiration :
<button type="button" onclick="KR.fields.focus('kr-expiry')">Focus expiry field</button>
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. |
KR.setFormConfig({'kr-label-do-register': 'custom'}) | Définit le label de la case à cocher "Enregistrer ma carte" |
Cette methode retourne une promesse (promise).
KR.setBrand()
Force la détection du moyen de paiement. La méthode prend en paramètre le nom du moyen de paiement. Les valeurs supportées sont (non exhaustives):
- VISA
- VISA_DEBIT
- VISA_ELECTRON
- MASTERCARD
- MASTERCARD_DEBIT
- MAESTRO
- AMEX
- CB
- (...)
Attention : Si vous définissez une autre valeur, celle-ci sera envoyée sans modification à la plateforme de paiement. Si la valeur n'est pas supportée par la configuration de votre boutique, aucune transaction ne sera créée.
Pour réactiver la détection automatique, appelez KR.setBrand() sans paramètres.
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 error */ /* 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éclencher 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 :
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 :
<button class="kr-payment-button">Custom label</button>
Vous pouvez également insérer une variable qui représente le montant et la devise. Le client JavaScript effectura automatiquement le remplacement :
<button class="kr-payment-button">this will cost %amount-and-currency% !!</button>
Questions fréquentes
Vous trouverez ici la foire aux questions relative au client JavaScript.
Comment corriger les erreurs CORS ou "Unable to post message" au moment de payer ?
Déja, vous devez développer depuis un serveur web. L'accès à la page de test doit être réalisé avec http:// et non avec file://
Si vous utilisez le framework ionic ou cordova, vous devez explicitement déclarer les noms de domaines que le client JavaScript peut appeler. Pour cela il faut ajouter dans config.xml :
<allow-navigation href="https://static.scelliuspaiement.labanquepostale.fr/static/js/krypton-client/V4.0" />
Plus d'informations ici.
Comment configurer les CSP (Content Security Policy)
Si votre site web utilise les CSP (Content Security Policy), vous devez autoriser le client JavaScript à créer ses IFrames. Pour cela, vous devez ajouter les 3 directives suivantes :
Directive CSP | Valeurs |
---|---|
connect-src | https://static.scelliuspaiement.labanquepostale.fr |
frame-src | https://static.scelliuspaiement.labanquepostale.fr |
script-src | https://static.scelliuspaiement.labanquepostale.fr |
Exemple d'ajout dans les meta du head de votre page:
<meta
http-equiv="Content-Security-Policy"
content="
connect-src https://static.scelliuspaiement.labanquepostale.fr;
frame-src https://static.scelliuspaiement.labanquepostale.fr;
script-src https://static.scelliuspaiement.labanquepostale.fr;"
/>
Plus d'informations sur les CSP ici.
Si vous utlisez un moteur de détection de fraude externe (comme monitor+, clearsale, ...), vous devez également ajouter :
Directive CSP | Valeurs |
---|---|
connect-src | https://scelliuspaiement.labanquepostale.fr |
frame-src | https://scelliuspaiement.labanquepostale.fr |
script-src | https://scelliuspaiement.labanquepostale.fr |
Utilisation avancée
Pour voir tous les cas d'utilisation avancés, vous pouvez consulter les articles suivants :
DESCRIPTION | Article |
---|---|
Transmettre les champs en fonction de vos besoins | Cas d'utilisation |
Ajouter des champs de formulaire personnalisés | Champs additionnels |
Gérer les erreurs du formulaire de paiement | Gestion des erreurs |
Gestion des nouvelles tentatives de paiement (retry) | Gestion du retry |
Paramètres généraux du client JS | Paramètres généraux |
Exemples d'intégration
En fonction du framework JavaScript que vous utilisez sur votre site marchand, plusieurs exemples d'intégration sont disponibles ici :
Framework | Description |
---|---|
Vue.js | exemple d'intégration pour Vue.js |
React | exemple d'intégration pour React |
React + NextJS | exemple d'intégration avec React et NextJS |
Angular | exemple d'intégration pour Angular et TypeScript |
Ionic | exemple d'intégration pour Ionic |
require.js | exemple d'intégration avec RequireJS |
Javacript | Librairie générique à utiliser dans les framework javascripts |
[C#][csharp] | exemple d'intégration pour C# (.NET) |
python/flask | exemple en python avec le framework flask |
php/symfony | exemple en python en PHP avec symfony |