Creating a Cart Handoff

Whether you are choosing to do a Hosted Checkout or an Embedded Checkout of online payments, you will have to follow the process of instructing the PaymentExpress API about the cart that a user is about to check out. This process involves making an API request to the PaymentExpress API similar to below.

Necessary Details

You will need a few specific minimum bits of information to make this request. Many more parameters are also available to facilitate the transaction in your system, dictate how it shows up in PaymentExpress reports, etc.

• clientTransactionId - A unique identifier for this transaction that comes from your system of record.
• location - A PaymentExpress configured field indicating the "location" the payment is occurring, such as what physical office the payment is being taken at or what portion of your PaymentExpress payment portal the user will land on.
• URLs indicating the post-payment actions that will happen in the checkout process, for things such as canceling the transaction, displaying the receipt for the transaction, and possibly a postback URL.
• The items in the transaction, including the following required elements per item:
  • clientItemId - A unique identifier for this item that comes from your system of record.
  • description - A plain language description of the item to be checked out.
  • amount - The cost of the item in question, formatted in a standard USD format, such as "13.59".
    In addition, to help route funds appropriately after the transaction and make reporting as useful as possible, your implementation will include setting up a combination of the following per item:
  • type - The type of the item to be checked out, which is configured in PaymentExpress.
  • fundCategory - The funding category that the funds from this item should belong to.
  • department - A particular department within your environment to which this item and its funds belong.

Making An Online Cart Handoff Request

When you are ready to hand this cart off to PaymentExpress, you will make a request to our Online Cart API to create the cart in our system. The request is a POST request similar to the below.

POST /api/v1/pay/carts

{
    "request": {
        "clientTransactionId": "F4BEF9CACEECE59",
        "location": "<<defaultOnlineLocation>>",
        "resultUrls": {
            "receipt": "https://clientsite.gov/receipt"
        },
        "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 above request would create a cart to be checked out in our PaymentExpress payment portal with one item, totaling $1257.38 before fees. The response is simple:

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

This response is useful in two forms, depending on the type of integration you have opted for. Regardless of which integration type you have chosen, you should store this cartId with the clientTransactionId that you have provided for the cart, because it can be used to track the status of the cart using the Cart Status API.

Extended documentation on the Online Cart Handoff API is available in our API Reference. You may also continue on below, depending on your integration type.