JavaScript Elements SDK

JavaScript Elements SDK

elements

See it in GitHub

The PublicSquare JavaScript SDK makes it easy to build secure web applications that collect cardholder data using Elements.

Get started with our guide.

Before You Begin

This SDK requires the use of a Publishable API Key. Go to your Developers section and click Reveal for your Publishable Key and copy the value.

Installation

npm

npm install --save @publicsquare/elements-js

yarn

yarn add @publicsquare/elements-js

Versions

Recommended version: 1.16.1.

If you're testing against a production sandbox (test-mode transactions using a production account), you need to be on 1.16.1 specifically — older versions will not work for this scenario.

1.16.1 is the current fix, not the start of a version range. There is no confirmed compatibility beyond 1.16.1 yet — this section will be updated as new versions are released, rather than assumed to extend automatically.

Version compatibility

Version	Test mode against staging	Test mode against production
< 1.16.0	Works	Not supported
1.16.0	Works	Works, but requires an additional configuration parameter to route correctly. Not recommended — upgrade to 1.16.1 instead.
1.16.1	Works	Works automatically, no extra configuration needed

Starting in 1.16.1, Elements automatically detects your environment by inspecting your Publishable Key and routes accordingly. No additional setup is required beyond using the correct key for your environment.

If using the CDN

Elements is also available via CDN at https://js.publicsquare.com/index.js. This URL always serves the latest release, so once 1.16.1 is deployed, CDN users need no action to pick it up.

To pin to a specific version instead, reference it by its versioned path:

<script src="https://js.publicsquare.com/v1.16.1/index.js"></script>

If using npm

Check your installed version:

npm list @publicsquare/elements-js

Upgrade to the confirmed fix version:

npm install --save @publicsquare/elements-js@1.16.1

Install the specific version above rather than @latest — 1.16.1 is the confirmed fix, not necessarily the newest published version. Always confirm the actual latest version before installing it.

See the GitHub Releases page for the full version history and changelog.

Initialization

import { PublicSquare } from "@publicsquare/elements-js";

// In this context PublicSquare is a class
const publicsquare = await new PublicSquare().init("<PUBLISHABLE_API_KEY>");
// use Elements

Parameter	Required	Type	Description
apiKey	true	string	The Publishable API Key

If you try to to use any Elements feature before calling PublicSquare.init, or before its Promise has been fulfilled, you will get an error.