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:

Classes à utiliser pour la personalisation des champs :

Classes à utiliser pour la personalisation des "place holders" :

Classes à utiliser pour la personalisation des labels animés (spécifique au thème material) :

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 :

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 :

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 :

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 :

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 :

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

Gestion dynamique du formulaire (Ajout, retrait du DOM):

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 :

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 :

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.systempay.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 :

Exemple d'ajout dans les meta du head de votre page:

<meta
  http-equiv="Content-Security-Policy"
  content="
    connect-src https://static.systempay.fr;
    frame-src https://static.systempay.fr;
    script-src https://static.systempay.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 :

Utilisation avancée

Pour voir tous les cas d'utilisation avancés, vous pouvez consulter les articles suivants :

Exemples d'intégration

En fonction du framework JavaScript que vous utilisez sur votre site marchand, plusieurs exemples d'intégration sont disponibles ici :