Nearly Perpendicular Macaroons

    @lyracom/embedded-form-glue

    1.2.0 • Public • Published

    Embedded Form Glue JavaScript library

    Build Status npm version

    The embedded-form-glue Javascript library helps you to integrate a payment form into your favorite framework easily using npm or any similar tools.

    A simple payment form will look like:

    payment form

    Context

    Any credit card payment form should comply with PCI-DSS requirements. A classical integration displays the payment form on the bank page using a redirection. In this case, PCI-DSS requirements are done by your bank.

    If you want to integrate a payment form on your web-page and get it easier with PCI-DSS, you can use IFrames loaded from a PCI-DSS certified server.

    Lyra provides a Javacript library that helps you to integrate a payment form using standard HTML components on your website. The library will transform automatically each sensitive field (pan, security code, ...) into an IFrame loaded from Lyra servers.

    For this reason, the Lyra Javascript library must be loaded from the Lyra PCI-DSS certified servers. Consequently, it's not possible to add it in your package.json file like any other Javascript library.

    To make your life easier, we have created a glue library that helps you to include it into your build: the embedded-form-glue library.

    The embedded-form-glue glue library helps you to deal with:

    • async loading of the Lyra Javascript library
    • helps you to manage configuration even if the library is not yet loaded
    • preload payment form elements and display them quickly on slow network
    • various helpers to add, display or remove the payment form

    Installation

    Add the following package to your library:

    npm install --save @lyracom/embedded-form-glue
    # OR
    yarn global add @lyracom/embedded-form-glue

    Basic usage

    First you need to load the theme files in your HEAD section:

    <!-- theme and plugins. should be loaded in the HEAD section -->
    <link rel="stylesheet"
    href="https://[CHANGE_ME: JAVASCRIPT ENDPOINT]/static/js/krypton-client/V4.0/ext/classic-reset.css">
    <script
        src="https://[CHANGE_ME: JAVASCRIPT ENDPOINT]/static/js/krypton-client/V4.0/ext/classic.js">
    </script>

    note: Replace [CHANGE_ME] with your credentials and end-points.

    For more information about theming, take a look to Lyra theming documentation

    Import the component:

    import KRGlue from "@lyracom/embedded-form-glue";
    

    and Load the Lyra Javascript library:

    const publicKey = 'CHANGE_ME: YOUR PUBLIC KEY';
    const endPoint = 'CHANGE_ME: JAVASCRIPT ENDPOINT'; /* should include https:// */
    
    /* WARNING: You should always use promises chaining with KR method calls */
    KRGlue.loadLibrary(endPoint, publicKey) /* Load the remote library */
          .then(({KR}) => KR.setFormConfig({              /* set the minimal configuration */
            formToken: 'DEMO-TOKEN-TO-BE-REPLACED',
            'kr-language': 'en-US',                       /* to update initialization parameter */
          }))
          .then(({KR}) => KR.addForm('#myPaymentForm'))   /* create a payment form */
          .then(({KR, result}) => KR.showForm(result.formId)); /* show the payment form */

    note: Replace [CHANGE_ME] with your credentials and end-points. warning: You should always use promises chaining with KR method calls

    your first transaction

    The payment form is up and ready, you can try to make a transaction using a test card with the debug toolbar (at the bottom of the page).

    If you try to pay, you will have the following error: CLIENT_998: Demo form, see the documentation. It's because the formToken you have defined using KR.setFormConfig is set to DEMO-TOKEN-TO-BE-REPLACED.

    you have to create a formToken before displaying the payment form using Charge/CreatePayment web-service. For more information, please take a look to:

    Lyra Javascript methods

    The following methods helps you to deal with the Lyra Javascript Library loading steps:

    • KR.addForm([CSS class or id]) : Add a form into a div (insert HTML elements): return a promise with a formId
    • KR.showForm(formId): display an hidden form
    • KR.hideForm(formId): hide a visible form
    • KR.removeForms(): Remove all existing forms and events
    • KR.attachForm([CLASS OR ID]): Scan a DOM and attach the library to an existing DOM, return a formId

    See Lyra Javascript library reference for all complete reference guide.

    Using embedded-form-glue with javascript frameworks

    Using embedded-form-glue Javascript library is quite easy. Take a look to the following examples to see how to deal with:

    Framework Description
    vue.js vue example using vue-cli
    react.js react example using create-react-app
    next.js react + nextjs example
    angular angular example using Angular CLI

    Cutomize your form

    KR.addForm() adds a default form. If you want to customize your payment form with:

    • different field order
    • add an additional field
    • update the HTML structure to your need

    You can add your own HTML and attach it with KR.attachForm(). see framework examples for more details.

    Compilation

    To compile the library just run the next command to install the needed vendors for compilation:

    # With npm
    npm install
    # With yarn
    yarn install
    

    Install the webpack library following the official documentation Webpack Library

    And then run the compilation command with webpack:

    npm run build
    

    Testing

    To run the e2e tests (testcafe), first initialize the static server and execute the tests after that.

    npm run e2e-server
    npm run test
    

    Install

    npm i @lyracom/embedded-form-glue

    DownloadsWeekly Downloads

    2,212

    Version

    1.2.0

    License

    ISC

    Unpacked Size

    7.03 MB

    Total Files

    146

    Last publish

    Collaborators

    • s-yagues
    • yyoyo
    • alacarta
    • alex-fournier
    • moabi
    • gigaga