Embedded Checkout

If you would like to allow your users to check out their carts that you've created in the Cart Handoff Process, but prefer not to have them leave your application to do so, then an Embedded Checkout using our Checkout Widget could be the right tool for you.

To use the Checkout Widget for online payments, you will follow a very similar process to a Hosted Checkout. First, create a Cart in our Handoff Process from your system of record. Once this has been done, you can now load the checkout widget in your web application using our JavaScript Checkout Widget which you can include right in your application.

💳

Try Out Embedded Checkout

Want to see Embedded Checkout in action? With a couple simple steps, you can load our checkout widget live right here in the Developer Portal.

Step 1: Include Checkout Widget JavaScript in Your Site

You will need to embed a JavaScript include of the PaymentExpress Checkout Widget JavaScript into your application to be able to load the Checkout Widget. You can do so by including tags similar to the following in the head section of your HTML:

<script
  src="https://govhub.com/web/widgets/current/checkout.js"
  type="text/javascript"
  charset="utf-8"></script>

Step 2: Create a Cart Handoff

Following the procedure already outlined on our cart handoff documentation, you should create the cart you want the user to check out. Upon completing this process, you will have a response that looks something like this:

{
  "cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
  "checkoutURL": "https://govhub.com/<<govhubClient>>/<<defaultOnlineLocation>>/redirect/4ed4137c-3d89-44ad-92a1-c9f3e916f51e"
}

You can ignore the checkoutURL value in this response, as that is used for Hosted Checkout. However, you will want to use the cartId value, as it will be necessary for step 4.

Step 3: Create an HTML Element

In the HTML for your checkout page, you will need to include an HTML element with a known ID value where you would like the Checkout Widget to be loaded and rendered. It might look as simple as the following:

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

Step 4: Load the Checkout Widget

Once you have this cartId, you can easily instantiate the checkout widget right in your application, by calling the following JavaScript:

// The first parameter is an HTML selector for the element where you want to
// render the Checkout widget on your site.
CheckoutWidget.attach('#gsg-checkout', {
  // Your site's identifier. This is the "location" value 
  // you specified in the cart request.
  site: '<<defaultOnlineLocation>>',

  // Use 'demo' in your non-production environment to make test payments.
  // Use 'prod' in your production environment to make real payments.
  environment: 'demo',

  // The cart ID returned from the PaymentExpress Cart API:
  cartId: '{{ cartId }}',

  // We support 'en' and 'es':
  language: 'en',

  // This is called when the payment is completed:
  onSuccess: function () {
    showAlert('Payment complete')
  },

  // If you pass this handler, a "Cancel" button will be shown at the bottom of
  // the shopping cart view. When clicked, this function will be called.
  onCancel: function () {
    showAlert('Payment canceled')
  },

  // This is called if there is an error loading the widget or submitting the
  // payment. The widget will also display the error, but you may also wish to
  // record it in your own system.
  onError: function (error) {
    showAlert(error.message)
  },
})

That's it! Execute this code when you're ready to render the checkout, and you will get a shiny new instance of the checkout widget right in your application.

📘

Checkout Widget Support

For security, the widget uses cross-domain iframes to collect payment information without risk of tampering or interception. This widget supports all modern browsers.