Guides

Quickstart: Connect Checkout

Embed a prebuilt widget on your site to quickly and easily add payment processing

Suggest Edits

The Checkout Workflow is a set of prebuilt UI components that streamlines making a Payment. Getting started is straightforward, just follow the steps below.

See Using Connect Checkout for reference documention.

Get setup in the portal

Step 1: Create a Public Key in the Partner Portal

Login to your Portal account, and in the API Keys section, create a Public Key with the URL you will be hosting the widget on. For development purposes, this can be your localhost, but ultimately this URL should be the page you host your widget on.

Create a Client Secret

Step 2: Add logic to call our API to create a Client Secret

A Client Secret is simply a short-lived session that your widget will use to securely create resources for customers. Add some code to call the Client Secrets API with your API Key to generate a valid Client Secret.

Below, you can see some sample code written for Node.js:

const response = await fetch("https://connect.sandbox.plastiq.com/api/v2/client-secrets", {
  method: 'POST',
  headers: { api-key: 'your-api-key' }
})
const { clientSecret } = await response.json()

Step 3: Pass the Client Secret to your frontend

You'll need the Client Secret to load and make calls from the widget. Pass the Client Secret to the webpage you will load the widget on. Usually, you will be sending other resources (such as user account information) to this page, so adding it there would be simple and effective.

Add the Checkout code to your web page

Step 4: Add the library

We've built a start-workflows library to make adding a widget easy. Include the following script on your page:

<head>
  ...
  <script src="https://workflows.connect.sandbox.plastiq.com/libraries/start-workflows.js"></script>
</head>

Step 5: Create a Workflows object

Use the Public Key you created earlier and pass the correct environment value (either sandbox or prod):

const ConnectWorkflows = new window.ConnectWorkflows(publicKey, {
  environment: 'sandbox'
})

Step 6: Load the widget

You must have an HTML element on your page that the widget can be attached to when it is loaded. The following explanations will assume using something similar to the code below:

<div id="connect-checkout"></div>

When you're ready to display the Checkout widget, load the widget it to your page. In the example below, calling the loadCheckoutWidget() function would load the widget into the HTML element that has the following id: #connect-checkout:

function loadCheckoutWidget() {
  ConnectWorkflows.create('checkout', {
    clientSecret,
    parentElement: '#connect-checkout'
  })
}

👍

Congratulations

At this point, you've successfully implemented the Connect Checkout UI widget.

Additional configuration

The steps below are optional things you can add to improve your integration and customer experience.

Optional Step 1: Add callbacks

The Checkout widget can invoke a callback function you define, so that you can handle the following events during the workflow: successfully creating a resource, errors when creating a resource, or successfully completing a Payment submission. We strongly encourage adding callbacks to your implementation.

The SUCCESS payload contains the full API response payload for the resource created, so you can save the data. This is helpful for tracking, and for improving the customer experience on subsequent visits, which we'll show next.

See the sample code below for how you can add callbacks under the handlers object to handle events:

ConnectWorkflows.create('checkout', {
  clientSecret,
  parentElement: '#connect-checkout',
  handlers: {
    onSuccess: function (event) {
      // Example: Save data
      handleSuccess(event.data)
    },
    onError: function (event) {
      // Example: Log error
      handleError(event.data)
    },
    onComplete: function (event) {
      // Example: Navigate to next page
      handleComplete()
    },
  },
}

You can read more about callback response payload formats here.

Optional Step 2: Pass in data

The Checkout widget supports passing in data during the instantiation of the app, so that you can preload previously created resources or autofill certain fields. Previously created resources must have been created by the same Payer or be a globally available resource (such as a partner-scoped Recipient).

In the example below, we'll pass in a Payer ID so that a customer doesn't have to add their personal details again, and can load other resources (such as a card, or a recipeient) they've already created. We'll also pre-fill some payment data for them to ensure payment amounts and details are correct:

const customData = {
  payer: {
    id: 'c3dc1943-38cf-4a2f-962c-c85f16392d98'
  },
  paymentIntent: {
    details: {
      accountName: 'Example name',
      accountNumber: '12345678',
      memo: 'Invoice #SG-A24676-01',
    },
    targetAmount: {
      value: 1234.56,
    },
  }
}

function loadCheckoutWidget() {
  ConnectWorkflows.create('checkout', {
    clientSecret,
    parentElement: '#connect-checkout',
    ...customData
  })
}

You can read more about what data and flags you can pass in here.

Optional Step 3: Add a custom theme

You can add a custom theme by creating a theme object and passing it into the widget. Learn more about custom theming here.

const theme = {
  palette: {
    primary: {
      main: '#2ac979',
      contrastText: '#fff',
    },
  },
  overrides: {
    MuiButton: {
      text: {
        color: '#FFF',
       },
     },
   },
}

function loadCheckoutWidget() {
  ConnectWorkflows.create('checkout', {
    clientSecret,
    parentElement: '#connect-checkout',
    theme
  })
}

Webpage Example

The example below contains all the necessary frontend code required to implement a Checkout widget with all the optional elements included (you would still need to implement the backend Client Secret logic).

<html>
  <head>
    <script src="https://workflows.connect.sandbox.plastiq.com/libraries/start-workflows.js"></script>
  </head>

  <body>
    <div id="start-button" class="start-button" style="margin-top: 24px">
      <button onclick="loadConnectWorkflows()">Start Workflow</button>
    </div>
    <div id="connect-checkout"></div>

    <script>
      function loadConnectWorkflows() {
        const ConnectWorkflows = new window.ConnectWorkflows(publicKey, {
          environment: 'sandbox'
        })

        const checkoutWorkflow = ConnectWorkflows.create('checkout', {
          clientSecret,
          parentElement: '#connect-checkout',
          payer: {
            id: 'c3dc1943-38cf-4a2f-962c-c85f16392d98'
          },
          paymentIntent: {
            details: {
              accountName: 'Example name',
              accountNumber: '12345678',
              memo: 'Invoice #SG-A24676-01',
            },
            targetAmount: {
              value: 1234.56,
            },
          }
          handlers: {
            onSuccess: function (event) {
              console.log(event.data)
            },
            onError: function (event) {
              console.log(event.data)
            },
            onComplete: function (event) {
              console.log('complete!')
            },
          },
          theme: {
            palette: {
              primary: {
                main: '#2ac979',
                contrastText: '#fff',
              },
            },
            overrides: {
              MuiButton: {
                text: {
                  color: '#FFF',
                 },
               },
             },
          }
       })
     }
    </script>
  </body>
<html>

Updated 7 months ago