Skip to main content

Get started (Web SDK)

Prerequisites​

To use our Web SDK, you need:

  1. An active UI key from the Embedder Portal
  2. A page on your website where you can include a script tag in the <head> and mount UI components in the <body>

Install​

Our Web SDK ships as a hosted JavaScript bundle. Include the right URL for the environment you're integrating with:

<!-- Sandbox -->
<script src="https://sandbox.weavr.io/app/secure/static/client.1.js"></script>

<!-- Live -->
<script src="https://secure.weavr.io/app/secure/static/client.1.js"></script>

Loading the script exposes a window.OpcUxSecureClient global that the rest of the SDK calls through.

caution

Choose the URL that matches your target environment. Switch the URL when you move your app from sandbox to live.

Initialize the SDK​

Initialize the SDK once per page load by passing your UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key.:

<script type="text/javascript">
  // Replace YOUR_UI_KEY with the UI key from the Weavr Portal > API Credentials screen
  window.OpcUxSecureClient.init("YOUR_UI_KEY");
</script>

You can find your UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. on the API Credentials screen in the Weavr Portal.

Associate a user token​

Components that show or capture data tied to a specific user — for example, card number, CVV, or capture card PIN — also need a user authentication token. Associate it before mounting those components:

<script type="text/javascript">
  window.OpcUxSecureClient.associate(
    "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
    function () {
      console.log("associate success");
      // Mount user-scoped components here
    },
    function (e) {
      console.error("associate failed " + e);
    }
  );
</script>
warning

Card and PIN components require a stepped-up authentication token before they render or tokenize.

Customize the look and feel​

You can match the look and feel of our UI components to your app by configuring fonts globally at init time and applying styles per component at mount time.

Fonts​

Pass a fonts array when initializing the SDK to load custom fonts:

window.OpcUxSecureClient.init("YOUR_UI_KEY", {
  fonts: [
    {
      cssSrc:
        "https://fonts.googleapis.com/css?family=Be+Vietnam:100,100i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i",
    },
  ],
});

Styles​

Pass a style object when mounting a component:

window.OpcUxSecureClient.associate(
  "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
  function () {
    var span = window.OpcUxSecureClient.span(
      "cardNumber",
      "YOUR_CARDNUMBER_TOKEN",
      {
        style: {
          fontSize: "12px",
        },
      }
    );
    span.mount(document.getElementById("cardNumber"));
  },
  function (e) {
    console.error("associate failed " + e);
  }
);

The style object supports these properties:

  • color
  • fontFamily
  • fontSize
  • fontSmoothing
  • fontStyle
  • fontVariant
  • fontWeight
  • height
  • letterSpacing
  • lineHeight
  • margin
  • padding
  • textAlign
  • textDecoration
  • textIndent
  • textShadow
  • textTransform

States​

You can apply different styles for different component states:

  • base — the default state for all components
  • empty — applies to input components when the input is cleared
  • valid — applies to input components when the user input passes validation
  • invalid — applies to input components when the user input fails validation

Pseudo-classes​

You can target specific user interactions using these pseudo-classes:

  • :hover
  • :focus
  • ::placeholder
  • ::selection
  • :-webkit-autofill

Combine states and pseudo-classes for fine-grained control:

var form = window.OpcUxSecureClient.form();
var input = form.input("password", "password", {
  placeholder: "Password",
  maxlength: 20,
  style: {
    base: { ":hover": { fontSize: "12px" } },
    empty: {},
    valid: {},
    invalid: {},
  },
});
input.mount(document.getElementById("password"));

Framework support​

If you're integrating from a JavaScript framework rather than vanilla HTML, see framework support for guidance specific to Vue.js and React.

Next steps​

With the SDK loaded and initialized, you can integrate components:

  • Login components — sign users in with password or passcode
  • Card components — show or capture card number, CVV, and PIN
  • KYC — verify consumersConsumers Individual persons who can be onboarded as identities on Weavr. Consumer identities represent individual customers and require Know Your Customer (KYC) verification. For consumers, the card owner and card assignee are typically the same person.
  • KYB — verify corporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. and their directors
  • Push provisioning — add cards to Apple Pay or Google Pay (coming soon on the web)