Guides

Connect UI Component

Embed a Plastiq-hosted UI component into your webpage to avoid touching sensitive information

Suggest Edits

Overview

Connect.js is a customizable, Plastiq-hosted UI component which can be embedded into a web or mobile application and used to collect Payment Method information. Because all payment details flow through and are tokenized by Plastiq Connect APIs, your systems never handle PCI scoped data.

How it works

The Connect UI component workflow can be simplified into 3 steps:

  1. You embed the Connect UI component on your page and send it a Client Secret and Payer ID so that we know who the user entering the data is.
  2. The User enters their PCI-sensitive information in our hosted UI and submits the form.
  3. We tokenize the card and send you a payload containing all the data you need to continue on to making a Connect Payment.

Setting up Connect.js

Importing the code
Connect.js is available as an npm package and can be found here. To include the package in your project, simply install and import the code as module:

# bash npm install example
npm install --save plastiq-connect

# yarn
yarn add plastiq-connect

// ES6
import Connect from "plastiq-connect";

This will give you access to the Connect object, which you can use to initialize the UI component and embed it into your page as an iFrame.

Alternatively, the source code is hosted by Plastiq at this URL and can be included in your raw HTML like below:

<head>
  ...
  <script src="https://assets.connect.plastiq.com/connectjs"></script>
</head>

Adding the parent div element
As the final requirement, you will need to add an empty div with the id of plastiq-connect-iframe-container to your code. A raw HTML example can be seen below:

<body>
  ...
  <div id="plastiq-connect-iframe-container"></div>
</body>

🚧

Where the iFrame gets bound

Connect.js requires hosting HTML page to contain an empty div with the id of plastiq-connect-iframe-container. This div is required in order for the library to correctly create an iframe element and bind itself as a child element to.

Supported Styles and Configurations
Connect.js accepts an optional object upon initialization that can be used to override certain default CSS and text . The following properties are supported:

PropertyParent objectDescription
backgroundColor
(String)		stylesThe backgroundColor for the component. Must be a valid hexadecimal color value.
primaryColor
(String)		stylesThe primary color for the component. Used to change the color of the submit button. Must be a valid hexadecimal color value.
errorColor
(String)		stylesThe color for the error text shown after failed submission. Must be a valid hexadecimal color value.
paymentMethodType
(String, enum)		configThe types of payment methods supported in the form. Can only be one of: "BOTH", "CARD", "BANK". Defaults to "BOTH".
minWidth
(Integer)		configThe minimum width, in pixels, that would change the form layout to a single-row / mobile view.
buttonText
(String)		configThe text for the form submission button.
errorText
(String)		configThe text shown after failed submission.

Event Callback functions
During initialization, the Connect UI component requires you to pass callback functions for handling success and error responses for a form submission.

Callback functionDescription
onSuccessA callback function for handling responses from Plastiq Connect when a Payment Method request payload successfully tokenized.

The event payload contains the successful response payload from Plastiq Connect.
onErrorA callback function for handling responses from Plastiq Connect when a Payment Method request payload failed to tokenize.

The event payload contains the error response payload from Plastiq Connect in the standard error format.

📘

Sandbox Mode

You can initialize a Connect .js object with sandbox: true flag. Setting this to true will send requests to the Plastiq Connect Sandbox environment and add additional logging to the console for debugging purposes.

Below is an example of initializing a Connect.js object with some configurations and callbacks:

var connect = new Connect({
  styles: {
    backgroundColor: '#FF0000',
    primaryColor: '#0000FF',
  },
  config: {
    buttonText: 'Submit Card',
    paymentMethodType: "CARD",
    minWidth,
  },
  onSuccess: mySuccessHandlerFunction,
  onError: myErrorHandlerFunction,
  sandbox: true,
})

Passing required data
In order to successfully send a payload to Plastiq, we require a Client Secret to be generated server-side and passed into the Connect object, along with the Payer ID the data is tied to (and which was used to generate the Client Secret). The initialized Connect object contains a sendData function which accepts a javascript object that you can use to send this information. See the example below:

Connect.sendData({
   payerId: "d9808127-533d-48cd-a2ba-ffe399e6f1ef",
   clientSecret: "lzrcpMwsMp1LKkVe56Jua+9LOSTeGv9xzPvNLJRWj2s="
});

Putting it all together

The following is an example of how you can tie Connect.js into an existing HTML page, including adding custom CSS:

<!DOCTYPE html>
<html lang="en">
    <head>
        ...
        <script type="module" src="https://assets.connect.plastiq.com/connectjs"></script>
    </head>
    <body>
        ...
        <div id="plastiq-connect-iframe-container"></div>
      
        <script type="text/javascript">
            var connect = new Connect({
              styles: {
                backgroundColor: '#FF0000',
                primaryColor: '#0000FF',
              },
              config: {
                buttonText: 'Submit Card',
                paymentMethodType: "CARD",
                minWidth,
              },
              onSuccess: mySuccessHandlerFunction,
              onError: myErrorHandlerFunction,
              sandbox: true,
            });
          
          connect.sendData({
            payerId: "d9808127-533d-48cd-a2ba-ffe399e6f1ef",
            clientSecret: "lzrcpMwsMp1LKkVe56Jua+9LOSTeGv9xzPvNLJRWj2s="
          });
        </script>
    </body>
</html>

This is just an example, and scripts with type="module" do not support Cross Origin sources. We recommend either importing the npm package as a module in your Javascript code, or wrapping the connect source code in a local module to overcome CORS restrictions.

Updated almost 4 years ago