@magensa/te-connect-js NPM

TEConnect JS

JavaScript module used to interact with TEConnect.

Getting Started

npm install @magensa/te-connect @magensa/te-connect-js

yarn add @magensa/te-connnect @magensa/te-connect-js

or via CDN:

    <script src="https://cdn.magensa.net/te-connect/1.1.1/te-connect.js"></script>
    <script src="https://cdn.magensa.net/te-connect-js/1.1.1/te-connect-js.js"></script>

Manual Card Entry

This document will cover the card manual entry utility that TEConnect offers.
TEConnect also offers a Payment Request utility as well, with both Apple Pay and Google Pay supported. Payment Request Documentation can be found here
Below we will begin with a step-by-step integration of the card manual entry utility.
If you would prefer to let the code speak, below we have two example implementations. One is using npmjs - while the other uses our CDN

Step-by-step

The first step is to create a TEConnect instance (from te-connect), and feed that instance to the TeConnectJs (from te-connect-js) constructor.

main.js

import { createTEConnect } from '@magensa/te-connect';
import { TeConnectJs } from '@magensa/te-connect-js';

function demoInit() {
    var teInstance = createTEConnect("__your_public_key_here__");
    var teConnect = new TeConnectJs(teInstance);
}

demoInit();

Next, design your page according to your specifications - and create a <div> with a unique id. Mount the TEConnect Card Entry on that div.

index.html

<body>
    <div id="example-div"></div>
    <script src='main.bundle.js'></script>
</body>

main.js

import { createTEConnect } from '@magensa/te-connect';
import { TeConnectJs } from '@magensa/te-connect-js';

function demoInit() {
    var teInstance = createTEConnect("__your_public_key_here__");
    var teConnect = new TeConnectJs(teInstance);

    teConnect.mountCardEntry('example-div');
}

demoInit();

Finally, to submit the card values, attach the createPayment method to a click handler of your choosing.

index.html

<body>
    <div id="example-div"></div>
    <button type="button" id="pay-button">Create Payment</button>
    <script src='main.bundle.js'></script>
</body>

main.js

import { createTEConnect } from '@magensa/te-connect';
import { TeConnectJs } from '@magensa/te-connect-js';

function demoInit() {
    var teInstance = createTEConnect("__your_public_key_here__");
    var teConnect = new TeConnectJs(teInstance);

    teConnect.mountCardEntry('example-div');

    function createPaymentClick() {
        return teConnect.createPayment()
            .then(resp => {
                if (resp.error) {
                    //Not successful - see error
                }
                else {
                    //Successful - see response
                }
            })
            .catch(err => console.error(err));
    }

    document.getElementById('pay-button').addEventListener('click', createPaymentClick);
}

demoInit();

There are two ways to inject your own styles into the Card Entry fields. One method is static (define styles when mounting), while the other is dynamic (utilize the setStyles method). The example implementation uses both of these methods to demonstrate various ways you can control your custom styles. See the complete styles API for more details.
Optionally, you may hide the ZIP input box, as demonstrated below. Once the input is hidden, the billingZip parameter becomes optional. If you still wish to provide a billingZip without rendering the input - you may do so, as demonstrated below (this would hide the ZIP input field, but would still create a payment token with the billingZip provided in the call).
However, if you wish to omit the billingZip completely, you may do so by hiding the zip input and passing no parameters to the createPayment function.

index.html

<body>
    <div id="example-div"></div>
    <button type="button" id="pay-button">Create Payment</button>
    <script src='main.bundle.js'></script>
</body>

main.js

import { createTEConnect } from '@magensa/te-connect';
import { TeConnectJs } from '@magensa/te-connect-js';

function demoInit() {
    var teInstance = createTEConnect("__your_public_key_here__", { hideZip: true });
    var teConnect = new TeConnectJs(teInstance);

    teConnect.mountCardEntry('example-div');

    var exampleZipCode = "90025";

    function createPaymentClick() {
        return teConnect.createPayment(exampleZipCode)
            .then(resp => {
                if (resp.error) {
                    //Not successful - see error
                }
                else {
                    //Successful - see response
                }
            })
            .catch(err => console.error(err));
    }

    document.getElementById('pay-button').addEventListener('click', createPaymentClick);
}

demoInit();

TEConnect Options

type TecPaymentRequestOptions = {
    appleMerchantId?: string,
    googleMerchantId?: string
}

type CreateTEConnectOptions = {
    hideZip?: boolean,
    tecPaymentRequest?: TecPaymentRequestOptions
}

createPayment Return Objects

These are the possible objects that will be returned successfully from the createPayment function. Thrown errors will be thrown as any other async method.

Success:

{
    magTranID: String,
    timestamp: String,
    customerTranRef: String,
    token: String,
    code: String,
    message: String
    status: Number,
    cardMetaData: null | {
        maskedPAN: String,
        expirationDate: String,
        billingZip: null | String
    }
}

Bad Request

{
    magTranID: String,
    timestamp: String,
    customerTranRef: String,
    token: null,
    code: String,
    message: String,
    error: String,
    cardMetaData: null
}

Error (Failed Validation, Timeout, Mixed Protocol, etc)

{ error: String }

Styles API

The styles object injected is comprised of two main properties:

base
- General styles applied to the container.
boxes
- Styles applied to the input elements.

Below we have the complete API with examples of default values for each.

Base

Property Name	Parent Property	Input Type	Acceptable Values	Default Value	Notes
backgroundColor	base	`string`	jss color (rgb, #, or color name)	`"#fff"`	container background color
margin	wrapper	`string` or `number`	jss spacing units (rem, em, px, etc)	`'1rem'`	container margin
padding	wrapper	`string` or `number`	jss spacing units (rem, em, px, etc)	`'1rem'`	container padding
direction	wrapper	`string`	`'row', 'row-reverse', 'column', 'column-reverse'`	`'row'`	`'flex-direction'` style property
flexWrap	wrapper	`string`	`'wrap', 'wrap', 'wrap-reverse'`	`'wrap'`	`'flex-wrap'` style property
inputType	variants	`string`	`"outlined", "filled", "standard"`	`"outlined"`	template design for input boxes
inputMargin	variants	`string`	`"dense", "none", "normal"`	`"normal"`	template padding & margins for input boxes
autoMinHeight	variants	`boolean`	`boolean`	`false`	`true` will maintain a static margin on each input box that will not grow with validation errors

Default Base Object:

{
    base: {
        wrapper: {
            margin: '1rem',
            padding: '1rem',
            direction: 'row',
            flexWrap: 'wrap'
        },
        variants: {
            inputType: 'outlined',
            inputMargin: 'normal',
            autoMinHeight: false
        },
        backgroundColor: '#fff'
    }
}

Boxes

Property Name	Input Type	Acceptable Values	Default Value	Notes
labelColor	`string`	jss color (rgb, #, or color name)	`"#3f51b5"`	label text and input outline (or underline) color
textColor	`string`	jss color (rgb, #, or color name)	`"rgba(0, 0, 0, 0.87)"`	color of text for input value Also applies :onHover color to outline/underline
borderRadius	`number`	numerical unit for css `border-radius` property	4	border radius for input boxes
inputColor	`string`	jss color (rgb, #, or color name)	`"#fff"`	input box background color
errorColor	`string`	jss color (rgb, #, or color name)	`"#f44336"`	Error text and box outline (or underline) color

Default Boxes Object:

{
    boxes: {
        labelColor: "#3f51b5",
        textColor: "rgba(0, 0, 0, 0.87)",
        borderRadius: 4,
        errorColor: "#f44336",
        inputColor: "#fff"
    }
}

Example Implementation

index.html

<body>
    <h1>TEConnectJS Example</h1>
    <div id="example-div"></div>
    <button type="button" id="pay-button">Create Payment</button>
    <button type="button" id="change-styles">Change Styles</button>
    <script src='main.bundle.js'></script>
</body>

main.js

import { createTEConnect } from '@magensa/te-connect';
import { TeConnectJs } from '@magensa/te-connect-js';

function demoInit() {
    var teInstance = createTEConnect("__your_public_key_here__");
    var teConnect = new TeConnectJs(teInstance);

    var exampleStyles = {
        base: {
            wrapper: { 
                margin: 0, 
                padding: 0
            },
            variants: {
                inputType: 'outlined',
                inputMargin: 'dense'
            },
           backgroundColor: 'rgb(66, 66, 66)'
        },
        boxes: {
          labelColor: "#BB86FC",
          textColor: "#BB86FC",
          borderRadius: 10,
          errorColor: "#CF6679",
          inputColor: '#121212'
        }
    };

    teConnect.mountCardEntry('example-div', exampleStyles);

    function createPaymentClick() {
        return teConnect.createPayment()
            .then(resp => {
                if (resp.error) {
                    //Not successful - see error
                }
                else {
                    //Successful - see response
                }
            })
            .catch(err => console.error("[Catch]:", err));
    }

    function changeStyles() {
        var colorful = {
            base: {
                wrapper: { 
                    margin: 0, 
                    padding: 0
                },
                variants: {
                    inputType: 'filled',//'outlined', 'filled', 'standard'
                    inputMargin: 'dense'  //'dense', 'none', 'normal'
                },
               backgroundColor: '#f44336'
            },
            boxes: {
                textColor: "#90ee02",
                borderRadius: 2,
                errorColor: "#2196f3",
                inputColor: '#ff7961'
            }
        };

        teConnect.setStyles(colorful);
    }

    document.getElementById('pay-button').addEventListener('click', createPaymentClick);
    document.getElementById('change-styles').addEventListener('click', changeStyles);
}

demoInit();

Example Implementation CDN

An important note about CDN versioning:

All te-connect-js versions will be available via CDN. You can see the version in the path below.
If you are starting a new project - it is recommended to start with the most recent version. Therefore, even if you are not using npmjs, it is still recommended to view the most recent published version at npmjs, so that you may target the most recent version. CDN and npm packages are versioned simultaneously.
Alternatively - if your project requires a specific version - you may target that version in the CDN path.

index.html

<body>
    <h1>TEConnectJS Example</h1>

    <div id="example-div"></div>
    <button type="button" id="pay-button">Create Payment</button>
    <button type="button" id="change-styles">Change Styles</button>

    <script src="https://cdn.magensa.net/te-connect/1.1.1/te-connect.js"></script>
    <script src="https://cdn.magensa.net/te-connect-js/1.1.1/te-connect-js.js"></script>

    <script>
        function demoInit() {
            var teInstance = window["te-connect"].createTEConnect("__your_public_key_here__");
            var teConnect = new window["te-connect-js"].TeConnectJs(teInstance);

            var exampleStyles = {
                base: {
                    wrapper: { 
                        margin: 0, 
                        padding: 0
                    },
                    variants: {
                        inputType: 'outlined',
                        inputMargin: 'dense'
                    },
                    backgroundColor: 'rgb(66, 66, 66)'
                },
                boxes: {
                    labelColor: "#BB86FC",
                    textColor: "#BB86FC",
                    borderRadius: 10,
                    errorColor: "#CF6679",
                    inputColor: '#121212'
                }
            };

            teConnect.mountCardEntry('example-div', exampleStyles);

            function createPaymentClick() {
                return teConnect.createPayment()
                    .then(resp => {
                        console.log(resp);

                        if (resp.error) {
                            //Not successful - see error
                        }
                        else {
                            //Successful - see response
                        }
                    })
                    .catch(err => console.error("[Catch]:", err));
            }

            function changeStyles() {
                var colorful = {
                    base: {
                        wrapper: { 
                            margin: 0, 
                            padding: 0
                        },
                        variants: {
                            inputType: 'filled',
                            inputMargin: 'dense'
                        },
                    backgroundColor: '#f44336'
                    },
                    boxes: {
                        textColor: "#90ee02",
                        borderRadius: 2,
                        errorColor: "#2196f3",
                        inputColor: '#ff7961'
                    }
                };

                teConnect.setStyles(colorful);
            }

            document.getElementById('pay-button').addEventListener('click', createPaymentClick);
            document.getElementById('change-styles').addEventListener('click', changeStyles);
        }

        demoInit();
    </script>
</body>

@infinitebrahmanuniverse/nolb-_mag @everything-registry/sub-chunk-570 @zalastax/nolb-_mag

7 months ago

7 months ago

1 year ago

2 years ago

2 years ago