Taking Payments in Person: Hosted Checkout
Overview
The In-Person Hosted Checkout workflow is simple:
- The cashier selects items in your system of record.
- Your system hands the cart off to PaymentExpress via API.
- The customer completes payment at a PIN pad.
Step 1: Cashier determines the items the customer will pay for
The cashier, using your system of record, identifies which items the customer is paying for. Once selected, your system will gather key details (item IDs, descriptions, amount due, etc.) and prepare to send them to PaymentExpress in a cart-creation request.
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 https://env.gsg.tech/api/v1/pay/carts/otc, where env is either beta, demo, or empty for production.
Example Request
POST /api/v1/pay/carts/otc
{
"request": {
"clientTransactionId": "F4BEF9CACEECE59",
"location": "DEFAULTOTCLOCATION",
"resultUrls": {
"receipt": "https://clientsite.gov/receipt"
},
"meta": {
"extra information": "here"
}
},
"otc": {
"cashier": {
"name": "DEFAULTCASHIER"
},
},
"items": [
{
"clientItemId": "1029347859728",
"description": "Property Taxes for Account #2890345",
"amount": "1257.38",
"type": "DEFAULTOTCITEMTYPE",
"fundCategory": "DEFAULTOTCFUNDCATEGORY",
"meta": {
"extendedDescription": "value",
"extra reporting info": "here"
}
}
],
}The above request would create a cart with one item in our PaymentExpress payment portal, totaling $1,257.38 before fees.
For request body field details, see the OTC checkout API reference.
Step 3: Redirect cashier to PaymentExpress’s Cashiering Page
After a successful request, you will receive a response like the one below. Use the checkoutURL value to redirect the cashier to PaymentExpress’s Cashiering page.
{
"cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
"checkoutURL": "https://govhub.com/test-client/propertytax/redirect/4ed4137c-3d89-44ad-92a1-c9f3e916f51e"
}Response Body Content
| Field | Description |
|---|---|
cartId | The cartId is the unique identifier for the cart created via the API. Your application can use this ID in multiple ways, and it must store the value until it successfully exchanges it for paymentId, the unique payment confirmation number, or the cart expires. |
checkoutURL | URL the cashier should be directed to in order to complete the transaction described in the cart. |
Example Errored Response
{
"errorCode": "BadRequest",
"errorMessage": "Unable to process cart_token API request for location propertytax at client test-client."
}When an error occurs, review your field values and ensure that all required identifiers (such as location, fundCategory, etc.) are valid and configured correctly.
Updated 2 days ago
