Using Connect Checkout

The Checkout Workflow is a set of prebuilt UI components that streamlines making a Payment. By starting a checkout session with the Workflows Javascript library, you can enable the full Checkout UI.

See the Quickstart guide for getting up and running with Connect Checkout quickly.

How it works

Implementing the Checkout Workflow can be done in a few steps:

1. Create a Public Key in the Connect Developer Portal.
2. Embed the Checkout UI on your page, and supply it with your Public Key.
3. Create a new Connect Checkout session when a user is ready to use the UI by supplying it with a secure Client Secret.
4. Users follow the flow and create a Payment.

Client Secrets and Scoping

📘

Client Secrets and iFrames

In order to create a valid session where users can securely make Payments, the Checkout Workflow requires a valid Client Secret to be passed in when loading the iFrame. Client Secrets can be made via a backend API call to the Client Secret API.

This guide assumes you have setup the logic to generate a Client Secret for your session, and that you're able to send that Client Secret to your front end code when instantiating the iFrame.

Client Secrets are used to authorize requests from the Checkout Workflow. The following Scenarios outline how you can expect Client Secrets to function during the Workflow:

• If you are creating a Payer during the Workflow, you must provide a non-Payer-scoped Client Secret during instantiation (that is, your Client Secret should not be scoped to anothe Payer ID). Once a Payer is created, the provided Client Secret will automatically be scoped to that Payer.
• If you are not creating a Payer and providing a Payer ID during instantiation, you must create a Client Secret uses the same Payer ID.
  • Similarly, if you are using an alternative Workflow to create isolated resources (like Card Capture), you will need to provide a Payer-scoped Client Secret.

See the Client Secrets documentation for more details.

Callbacks

The Checkout Workflow will invoke the callback function you define when you create a new session with a full Connect API payload, so that you can handle the following events during the workflow: successfully creating a resource, errors when creating a resource.

Callback Payloads

Click through the tabs to see examples of the various callback payloads.

{
    "object": "PAYER", // PAYER | RECIPIENT | PAYMENT_METHOD | PAYMENT_INTENT | PAYMENT
    "status": "SUCCESS",
    "data": {
        "id": "f33dadc3-9d3d-4416-8c55-1fd8cde8e619",
        "businessAddress": null,
        "businessName": "Test business",
        "contact": {
            "firstName": "Test",
            "lastName": "Payer",
            "email": "[email protected]",
            "phone": "11231231231"
        },
        "createdAt": "2024-04-19T13:46:27.000Z",
        "status": "ACTIVE"
    }
}

{
    "object": "PAYMENT_METHOD",
    "status": "ERROR",
    "data": {
        "message": "Your payment method could not be saved.",
        "code": "CREATE_PAYMENT_METHOD_FAILED"
    }
}

{
    "object": "PAYMENT",
    "status": "COMPLETE"
}

{
    "object": "PAYMENT_INTENT",
    "status": "BACK"
}

Example

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

const checkoutWorkflow = ConnectWorkflows.create('checkout', {
	...
  handlers: {
    onSuccess: function (event) {
      console.log('onSuccess Handler, data: ', event)
    },
    onError: function (event) {
      console.log('onError Handler, data: ', event)
    },
    onBack: function (event) {
      console.log('onBack Handlder, data:', event)
    }
    onComplete: function (event) {
      console.log('onComplete Handler, data:', event)
    },
  },
})

Passing in data

The Checkout Workflow 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).

Aside from passing in resources, you can also pass in specific boolean flags to invoke certain behaviors:

Below is an example of showcasing passing in both previously created resources, and autofilling payment fields:

const checkoutWorkflow = ConnectWorkflows.create('checkout', {
  ...
  recipient: {
    id: 'recipientId',
  },
  payer: {
    id: 'payerId',
  },
  paymentIntent: {
    readOnly: true,
    disableDocumentUpload: true,
    details: {
      accountName: 'Test Account',
      accountNumber: "1234567890",
      memo: 'Test memo',
    },
    targetAmount: {
      value: '3000000.00',
    },
  },
  paymentReview: {
    showDeliveryInformation: true,
  },
  defaultCountry: 'ca',
})

Note: The paymentIntent pass-in object supports the readOnly boolean flag, which is false by default. If set to true, this will allow you to initiate a Checkout Workflow session with prefilled values that your user can view but not modify.

Custom Styles and Themes

The Checkout Workflow supports passing in a custom theme JSON object that would override the styles for any of the components you select. This object acts as a theme that can be applied globally. We use Material UI themed components in our Workflows Components; you can learn more information about how to override styles here: https://mui.com/material-ui/customization/theme-components/

Below is an example of some custom styles you can use to override base styles that come out of the box:

const customTheme = {
  "typography": {
    "fontFamily": "verdana"
  },
  "palette": {
    "primary": {
      "main": "#FFA500"
    }
  },
  "components": {
    "MuiButton": {
      "styleOverrides": {
        "root": {
          "fontSize": "5rem"
        }
      }
    }
  }
}

const checkoutWorkflow = ConnectWorkflows.create('checkout', {
  ...
  theme: customTheme
})

Alternative workflow configurations

Card Capture

📘

Client Secrets

Adding a card requires you to generate and pass in a Client Secret that is scoped to a Payer. See: https://docs.developer.plastiq.com/docs/client-secrets-overview

const customTheme = {
  "typography": {
    "fontFamily": "verdana"
  },
  "palette": {
    "primary": {
      "main": "#FFA500"
    }
  },
  "components": {
    "MuiButton": {
      "styleOverrides": {
        "root": {
          "fontSize": "5rem"
        }
      }
    }
  }
}

...

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

  const cardWorkflow = ConnectWorkflows.create('cardCapture', {
    clientSecret,
    parentElement: '#connect-card-capture',
    payer: {
      id: 'payerId',
    },
    handlers: {
      onSuccess: function (data) {
        console.log('onSuccess Handler, data: ', data)
      },
      onError: function (data) {
        console.log('onError Handler, data: ', data)
      },
      onCancel: function (data) {
        console.log('onCancel Handler, data: ', data)
      },
    },
    theme: customTheme
  })
}