Taking Online Payments: Embedded Checkout

Overview

Embedded Checkout keeps customers in your application while PaymentExpress securely collects tender information in an iframe-based widget. At a high level, you’ll determine items, create a cart via API, store identifiers, and embed and initialize the widget in your page.

💳

Try Embedded Checkout

Want to see Embedded Checkout in action? With a few steps, you can load the checkout widget live in the Developer Portal.

Step 1: Customer determines the items they will pay for.

Your online application will need a method to determine the items the customer will pay for. Once it determines the items, it must communicate them to PaymentExpress using a Cart Handoff.

Step 2: Tell PaymentExpress about the items.

When your application obtains the required authentication and is ready to hand the cart off to PaymentExpress for payment processing, you will make a request to our Cart API. The request is a POST request similar to the example below. All cart requests will go to the following URL, where env is beta, demo, or www:

https://env.gsg.tech/api/v1/pay/carts

Example request

POST /api/v1/pay/carts

{
  "request": {
    "clientTransactionId": "F4BEF9CACEECE59",
    "location": "DEFAULTONLINELOCATION",
    "resultUrls": {
      "receipt": "https://clientsite.gov/receipt",
      "postback": "https://clientendpoint.postback/"
    },
    "meta": {
      "customField": "value"
    }
  },
  "items": [
    {
      "clientItemId": "1029347859728",
      "description": "Property Taxes for Account #2890345",
      "amount": "1257.38",
      "type": "DEFAULTONLINEITEMTYPE",
      "fundCategory": "DEFAULTONLINEFUNDCATEGORY",
      "meta": {
        "extendedDescription": "value",
        "extraReportingInfo": "here"
      }
    }
  ]
}

The above request would create a cart with one item in our PaymentExpress payment portal, totaling $1257.38 before fees.

Request body content

See the Create Online Checkout Redirect API Reference for the required and optional cart request fields.

Step 3: Store identifier and prepare for the Embedded Widget

Example Response

After a successful request, you will receive a response like the one below.

{
  "cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
  "checkoutURL": "https://govhub.com/GOVHUBCLIENT/DEFAULTONLINELOCATION/redirect/4ed4137c-3d89-44ad-92a1-c9f3e916f51e"
}

Store cartId and map it to your clientTransactionId for reconciliation and retry flows. You will also use cartId to load the Checkout Widget in your application.

Ignore checkoutURL when using the Online Embedded Checkout solution. That field is used by Hosted Checkout.

Response body content

Example error response

{
  "errorCode": "BadRequest",
  "errorMessage": "invalid client/site: DEFAULTONLINELOCATION"
}

Review the Create Online Checkout Redirect API Reference for additional information.

Step 4: Include Checkout Widget JavaScript in Your Site

You will need to embed a JavaScript include of the PaymentExpress Checkout Widget JavaScript in your application 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 5: Add an HTML container for the Checkout Widget

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 6: Initialize the Checkout Widget

Call CheckoutWidget.attach with the site, environment, cart, language, and event-handler options:

// 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)
  },
})

When executed, the widget loads and the customer can complete payment without leaving your application.

📘

Checkout Widget support

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

How Information Displays to Your Customers

The images below illustrate how the description (1) and extendedDescription (2) fields will appear to the customer on the PaymentExpress payment and receipt pages.

Payment page

Receipt page