JavaScript client reference

The JavaScript client allows to create a payment form on your merchant website, using the following code:

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.systempay.fr/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://api.systempay.fr/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://api.systempay.fr/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded" 
   kr-form-token="DEMO-TOKEN-TO-BE-REPLACED">

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

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

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

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

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

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

For more detailed documentation, go to: Start: Single payment

Initialization parameters

Various parameters can be defined while loading the JavaScript client. For example, in order to define kr-public-key and kr-post-url-success:

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.systempay.fr/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ" 
   kr-post-url-success="paid.html">
  </script>

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

The available parameters are:

Parameter Required Description
kr-public-key yes Public key for making a payment.
kr-language   Language used for displaying the form in Culture format (en-US).
kr-post-url-refused   URL appelée lorsque toutes les tentatives ont échoué.(données transmises en POST)
kr-post-url-success   URL vers laquelle le formulaire est POSTé en cas de succès.(données transmises en POST)
kr-post-get-refused   URL appelée lorsque toutes les tentatives ont échoué.(données transmises en GET)
kr-post-get-success   URL vers laquelle le formulaire est POSTé en cas de succès.(données transmises en GET)
kr-clear-on-error   Disables the removal of CVV in case of rejected transaction (true or false).
kr-hide-debug-toolbar   Hides the debug sidebar in test mode (true or false).
kr-placeholder-expiry   Placeholder of the kr-expiry field (expiry date).
kr-placeholder-pan   Placeholder of the kr-pan field (card number).
kr-placeholder-security-code   Placeholder of the kr-security-code field (CVV).
kr-spa-mode   if true, form is not automatically initialized.(default is false)

Events

It is possible to attach custom JavaScript callbacks to different events. The JavaScript client supports the following events:

Parameter Description
KR.onError() Allows to be notified when an error occurs.
KR.onFocus() One of the form fields gets focus.
KR.onFormCreated() The payment form is ready but the content of iframes has not loaded yet.
KR.onFormReady() The form is ready to be used.
KR.onLoaded() First event called before creating the form.
KR.onSubmit() Called just before the form is POSTed.

Tous les évenements retournent des promesses, vous permettant dans les intégrer dans une chaine.voir Travailler dans un environement asynchrone pour plus d’information.

KR.onError()

KR.onError() allows to intercept errors before they appear.

Example of interception of error messages:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onError( function(event) {
            var code = event.errorCode;
            var message = event.errorMessage;
            var myMessage = code + ": " + message;

            document.getElementsByClassName("customerror")[0].innerText = myMessage;
          });
    });
  </script>

After that, error messages will automatically appear in the following element, if it is present:

When several errors are generated, they are merged into one single error. The children property will contain the details of all errors:

{
    "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,
    (...)
}

For more information on errors, go to: Managing errors (JS client)

KR.onFocus()

Kr.onFocus() allows to be notified when a form field is in focus:

Example of integration:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onFocus( function(event) {
            var myMessage = "focus on: " + event.field;

            $("#custommessage").html(myMessage);
          });
    });
  </script>

If the card number field is in focus, the event variable will take the following value:

{
    "field":"pan",
    "formId":"F73867",
    "_type":"krypton/focus"
}

KR.onSubmit()

KR.onSubmit() allows to intercept information about the authorized transaction before the form makes a POST to the URL defined with kr-post-success-url.

Example of integration:

  <script type="text/javascript">
    $(document).ready(function() {
      KR.onSubmit( function(event) {
        /* Change the button label to the orderStatus */
        $(".kr-payment-button > span:first").html(event.clientAnswer.orderStatus);
        $(".kr-spinner").hide();
        $(".kr-payment-button > span:first").show();
        
        /* return values:
         * true: kr-post-success-url is called using POST
         * false: kr-post-success-url is not called, execution stops.
         */
        return false;
      });
    });
  </script>

The object present in event is the same as the one POSTed by the form. For more information, go to: Go back.

The behavior varies depending on the boolean returned by your function:

Return value Behavior
false Default behavior: the JavaScript client makes a POST to kr-post-success-url.
true The post to kr-post-success-url has not been made. You manage the post-payment action yourself.

Methods

Several methods are available for interacting with the JavaScript client:

Parameter Description
KR.setFormConfig() Allows to modify the configuration of the JavaScript client right away, see the next section.
KR.setShopName() Change the name of the shop defined in the header of the pop-in.
KR.setFormToken() Shortcut allowing to change the formToken of the current form.
KR.validateForm() Triggers local validation of the form.

Tous les évenements retournent des promesses, vous permettant dans les intégrer dans une chaine.voir Travailler dans un environement asynchrone pour plus d’information.

See documentation on KR.validateForm() for more information.

You must use only documented methods. Undocumented elements are subject to change without a warning!

KR.setFormConfig()

This method allows to change the following elements right away:

Use Description
KR.setFormConfig({formToken: “NEW_FORM_TOKEN”}); Changes the current formToken.
KR.setFormConfig({language: “fr-FR”}); Changes the language of the payment form and the error messages.

This method returns a promise.

KR.validateForm()

This method checks locally if the form is valid. It returns a promise:

  • then() est appelé quand le formulaire est valide.result sera valorisé à nul.
  • catch() est appelé lorsque le formulaire est invalide.result contient le détail de l’erreur.

Example of a call:

KR.validateForm().then( ({KR, result}) => {
    /* there is no errors */
    /* 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();
    }
);

Once you have intercepted the errors, you can manually trigger the KR.onError() event by callingKR.doOnError();.

Button personalization

The payment button is automatically added to your form using the following code:

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

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

There are numerous benefits to using our payment button:

  • The labels are translated automatically.
  • The amount is automatically formatted and updated.
  • We handle the pending transition animation for you
  • The button automatically changes to read-only mode if necessary

If you want to manage the button label yourself, all you need to do is add it as follows:

You can also insert a variable that represents the amount and the currency. The javascript client will automatically perform the replacement:

Advanced use

To see all advanced use cases, go to JavaScript client features.