Overview

Hosted Checkout uses a simple redirect flow:

Create a cart using the Online Cart API.
Receive a cartId and checkoutURL.
Redirect the customer to PaymentExpress to complete payment.
Receive confirmation that the payment was completed.

After completion, your system finalizes the transaction through your regular reconciliation and notification flow.

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 is ready to hand the cart off to PaymentExpress for payment processing and obtains the required authentication, you will make a request to our Cart API, creating the cart in our system. The request is a POST request similar to the example below.

All cart requests will go to the https://env.gsg.tech/api/v1/pay/carts URL, where env is either beta, demo, or empty for production. To view more information on authentication, see the Getting Connected and Authenticated page.

Example Request

POST /api/v1/pay/carts

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

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

Request Body Content

Field	Who Provides the Value	Description
`clientTransactionId`	You	The client’s unique ID for the shopping cart or transaction. Use this field primarily to track transactions through the PaymentExpress process.
`location`	PaymentExpress	A PaymentExpress-configured field that indicates the location of the payment, such as the physical office taking the payment or the portion of your PaymentExpress payment portal where the user will land.
`resultUrls`	You	URLs indicating the post-payment actions that will occur during the checkout process, such as canceling the transaction, displaying the transaction receipt, and sending a postback.

Items in the cart include the following required elements per item:

Field	Who Provides the Value	Description
`clientItemId`	You	A unique identifier for the item from your system of record.
`description`	You	A plain-language description of the item.
`amount`	You	The cost of the item, formatted in standard USD, such as `13.59`.
`type`	You and PaymentExpress	The type of item the customer is paying for, which PaymentExpress configures.
`fundCategory`	PaymentExpress	The funding category to which the funds from this item should belong.
`department`	PaymentExpress	A particular department within your environment to which the item and its funds belong.

Step 3: Redirect the Customer to PaymentExpress

Example Response

After a successful request, you will receive a response like the one below. Use the checkoutURL value to redirect the customer to the PaymentExpress public site.

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

Response Body Content

Field	Description
`cartId`	The unique identifier for the cart created through the API. Your application can use this ID in multiple ways. Store it until it is successfully exchanged for a `paymentId`, the unique payment confirmation number, or until the cart expires.
`checkoutURL`	The URL to which the user should be directed to complete the transaction described in the cart.

Example Error Response

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

When an error occurs, review your field values and ensure that all required identifiers, such as location and fundCategory, are valid and configured correctly.

Review the Online Cart Handoff API documentation available in the API Reference for additional information.

How Information Displays to Your Customers

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

Taking Online Payments: Hosted Checkout