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 Getting started: Single payment.

Supported platforms

We make every effort to support all recent versions of the major browsers available on the market.

For security reasons and to deliver the best user experience to the majority of our merchants, we do not support browsers and operating systems that no longer receive security patches.

These browsers represent a minor part of the traffic making payments on the Internet.

We support:

  • Internet Explorer from version 10
  • Edge starting from version 17
  • Chrome from version 70
  • Firefox starting from version 64
  • Safari (Desktop and mobile) from version 11 onwards
  • Android native browser from Android 4.4 onwards
  • All the latest versions of IOS from iPhone 4S

TLS 1.2 must be supported by the browser.

We proactively test most browsers, both mobile and desktop. However, it is possible that a combination of mobile + browser eludes our attention. In this case, please contact our support team.

If you want to support a combination that is not supported by our JavaScript client, you can also implement our form with redirect for these limit cases.

Also note that some antivirus or ad-blocker software may block our solution. Please contact support if you notice any improper detection.

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:

General settings:

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-success   URL to which the form is submitted (POST method) in case of success.
kr-get-url-success   URL to which the form is submitted (POST method) in case of success.
kr-post-url-refused   URL called when all attempts have failed (POST method).
kr-get-url-refused   URL called when all attempts have failed (GET method).
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-spa-mode   if true, form is not automatically initialized (default is false).

Placeholder customization:

Parameter Required Description
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-placeholder-identity-document-type   Placeholder of the ID document type field, if required (LATAM case)
kr-placeholder-identity-document-number   Placeholder of the ID number field, if required (LATAM case)
kr-placeholder-installment-number   Placeholder of the Payment method field
kr-placeholder-card-holder-mail   Placeholder of the e-mail field, if required (LATAM case)
kr-placeholder-card-holder-name   Placeholder of the cardholder name field, if required (LATAM case)

Personalization of animated labels (specific to the material theme):

Parameter Required Description
kr-label-expiry   Animated label of the kr-expiry field (expiry date)
kr-label-pan   Animated label of the kr-pan field (card number)
kr-label-security-code   Animated label of the kr-security-code (CVV) field
kr-label-identity-document-type   Animated label of the ID type field, if required (LATAM case)
kr-label-identity-document-number   Animated label of the ID number field, if required (LATAM case)
kr-label-installment-number   Animated label of the Payment method field
kr-label-card-holder-mail   Animated label of the e-mail field, if required (LATAM case)
kr-label-card-holder-name   Animated label of the cardholder name field, if required (LATAM case)

These parameters can also be overridden with the KR.setFormConfig() method. For example, to override the kr-post-url-success parameter:

KR.setFormConfig({
        'kr-post-url-success': 'https://my.site'
    }).then(({
            KR
        }) => {
            /* there is no errors */
        );

Warning, if the kr-post-url-success and kr-get-url-success parameters are defined simultaneously, the POST method will have priority. The same applies to kr-post-url-refused and kr-get-url-refused*.

Events

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

Parameter Description
KR.onBrandChanged() Called when the card brand has been detected.
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.
KR.button.onClick() Called when the buyer clicks on the form button.

All events return promises, allowing you to integrate them into a chain. See Working in asynchronous environment for more information.

KR.onBrandChanged()

The callback defined in KR.onBrandChanged() is called each time a card brand is detected. Example of integration:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onBrandChanged( function({KR, cardInfo}) {
            var myMessage = "brand selected: " + cardInfo.brand;

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

The cardInfo object contains the brand property which can take the following values:

  • amex
  • cb
  • mastercard
  • maestro
  • visa_electron
  • visa

To view the complete list, see the reference documentation of the effectiveBrand parameter here: Payment.

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 contained in event is the same as the one posted by the form. For more details, go to: Browser return.

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

Return value Behavior
true The JavaScript client performs a POST on kr-post-success-url.
false The POST with kr-post-success-url is not made. You manage the post-payment action yourself.

KR.button.onClick()

KR.button.onClick() allows for custom processing before the JavaScript client validates the form and makes the call to create a transaction.KR.button.onClick() accepts either a callback or a promise as a parameter.

You can stop the execution string by returning false at the end of processing:

Return value Behavior
false The execution is interrupted. Error handling does not take place. The transaction is not created.
true The execution continues normally when the callback is executed.

Methods

Several methods are available for interacting with the JavaScript client:

Parameter Description
KR.closePopin() Closes the pop-in (if open).
KR.field.focus() Gives focus to an embedded form field.
KR.openPopin() Opens the pop-in (if closed).
KR.setFormConfig() Allows to override the JavaScript client configuration, see the next section.
KR.setShopName() Changes the name of the shop defined in the pop-in header.
KR.setFormToken() Shortcut for changing the formToken of the current form.
KR.validateForm() Triggers local validation of the form.

All events return promises, allowing you to integrate them into a chain. See Working in asynchronous environment for more information.

KR.field.focus()

To give focus to a form field, you can use the KR.field.focus(FIELD_CLASS) method. You must pass the class of the embedded form field as a parameter.

For example, to add a button that will set focus on the expiry date field:

KR.setFormConfig()

This method allows to override the initialization parameters, as well as the following elements:

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 error messages.

This method returns a promise.

KR.validateForm()

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

  • then() is called when the form is valid.result will be set to null.
  • catch() is called when the form is invalid.result contains the error detail.

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 trigger the KR.onError() event manually by callingresult.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, simply add it as follows:

You can also insert a variable that represents the amount and currency. The JavaScript client will automatically replace them:

Frequently Asked Questions

Here you will find the frequently asked questions about the JavaScript client.

How to correct CORS or "Unable to post message" errors upon payment?

First, you have to be developing from a web server. The test page must be accessed with http:// and not with file://.

If you use the ionic or cordova framework, you must explicitly declare the domain names that can be called by the JavaScript client. To do this, add the folowing in config.xml:

<allow-navigation href="" />

More information here.

Advanced use

To see all the advanced use cases, go to the following articles:

Description Article  
Adding custom form fields Additional fields  
Performing a single payment Start: Single payment  
Handling embedded form errors Error handling  
Handling new payment attempts (retry) Handling retries  
Event and method reference of the JS client JavaScript Client Reference  
Pre-configured themes and personalization with CSS Themes  
Switch from redirected form to embedded form Migrating the form with redirect