Connect UI Component
Embed a Plastiq-hosted UI component into your webpage to avoid touching sensitive information
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:
- 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. - The User enters their PCI-sensitive information in our hosted UI and submits the form.
- 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
ofplastiq-connect-iframe-container
. Thisdiv
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:
Property | Parent object | Description |
---|---|---|
backgroundColor (String) | styles | The backgroundColor for the component. Must be a valid hexadecimal color value. |
primaryColor (String) | styles | The primary color for the component. Used to change the color of the submit button. Must be a valid hexadecimal color value. |
errorColor (String) | styles | The color for the error text shown after failed submission. Must be a valid hexadecimal color value. |
paymentMethodType (String, enum) | config | The types of payment methods supported in the form. Can only be one of: "BOTH", "CARD", "BANK" . Defaults to "BOTH" . |
minWidth (Integer) | config | The minimum width, in pixels, that would change the form layout to a single-row / mobile view. |
buttonText (String) | config | The text for the form submission button. |
errorText (String) | config | The 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 function | Description |
---|---|
onSuccess | A 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. |
onError | A 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 script
s 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 over 2 years ago