Embedded In-Person Widget
Overview
Integrating with GSGPay, we offer two different types of Embedded Checkout Widgets. One utilizes the Grant Street Windows Application (GWA) API and one utilizes the Pin Pad Cloud Direct API. However both are designed to allow cashiers to facilitate in-person payments while reducing the number of API calls your application/site is required to make. In both cases, the widget loads directly on your application and it supports all modern browsers.
Step 1: Create a Cart to Pay
With a customer present at a cashiering location with a PIN pad available, the cashier would work in your system of record to select what items the customer is ready to make payment for. This can be one or more items in the same transaction depending on your needs.
When you are ready to hand this cart off to PaymentExpress for processing a payment, you will make a request to one of our Cart APIs to create the cart in our system. The request is a POST request similar to the below.
https://{env}.gsg.tech/api/v1/pay/inperson/carts
{
"request": {
"clientTransactionId": "F4BEF9CACEECE59",
"location": "DEFAULTOTCLOCATION",
"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": {
"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.
For more details on Embedded In-Person Cart Creation APIs, including the proper URLs to send these requests to, see our detailed API reference.
Once you have created a cart in the PaymentExpress system to hand off for payment, as noted you will receive a JSON response formatted as follows.
{
"cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
"fees": {
"CreditCard": {
"primary": "1257.38",
"fees": "1.23",
"total": "1258.61",
},
"DebitCard": {
"primary": "1257.38",
"fees": "1.23",
"total": "1258.61",
},
"ECheck": {
"primary": "1257.38",
"fees": "0.50",
"total": "1257.88"
}
}This response will contain 2 core details: the unique identifier of this cart (cartId) as well the fees associated with cost of the transaction based on tender type, including the primary amount, fee amount, and total cost of the transaction for your customer.
Step 2: Include Checkout Widget JavaScript in Your Site
You will need to include a JavaScript for the Checkout Widget in your cashiering application to load the checkout widget. Below are the URLs to use for each of our environments.
| Checkout widget | Environment | URL |
|---|---|---|
| Grant Street Windows Application (GWA) | Beta | https://beta-static.govhub.com/gwa-direct/gwa-direct.umd.cjs |
| Grant Street Windows Application (GWA) | Demo | https://demo-static.govhub.com/gwa-direct/gwa-direct.umd.cjs |
| Grant Street Windows Application (GWA) | Production | https://static.govhub.com/gwa-direct/gwa-direct.umd.cjs |
| Pin Pad Cloud Direct (PPC) | Beta | https://beta-static.govhub.com/ppc-direct/ppc-direct.umd.cjs |
| Pin Pad Cloud Direct (PPC) | Demo | https://demo-static.govhub.com/ppc-direct/ppc-direct.umd.cjs |
| Pin Pad Cloud Direct (PPC) | Production | https://static.govhub.com/ppc-direct/ppc-direct.umd.cjs |
For the Grant Street Windows Application Checkout Widget
<script
src="https://beta-static.govhub.com/gwa-direct/gwa-direct.umd.cjs"
type="text/javascript"
charset="utf-8"></script>For the Pin Pad Cloud Direct Checkout Widget
<script
src="https://beta-static.govhub.com/ppc-direct/ppc-direct.umd.cjs"
type="text/javascript"
charset="utf-8"></script>Step 3: Add an HTML container for the Checkout Widget
In the HTML for your cashiering application, 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. The height and width can be styled in the element itself.
<div id="gsg-widget"
Style: “max-width: 600px”
/>Step 4: Initialize the Checkout Widget
For the Grant Street Windows Application Checkout Widget
Call GWADirect.attach() on your site and pass the parameters documented below.
GWADirect.attach({
// An HTML selector for the element where you want to render the GWA Direct Widget
// widget on your site:
elementSelector: '#gsg-widget',
// The id of the cart to be checked out using the GWA Direct Widget.
cartId: ‘4ed4137c-3d89-44ad-92a1-c9f3e916f51e',
// The OAuth token to be used for requests to GSGPay
jwt: ‘ ’',
// Use 'demo' in your non-production environment to use test data.
// Use 'prod' in your production environment to use real data.
environment: 'beta',
// Optional: Display the option to manually enter payment information (default: false)
allowManualEntry: false,
// Optional: The GWA host (default: '127.0.0.1')
gwaHost: '127.0.0.1',
// This is called when the payment is completed.
onSuccess: function (paymentId) {
alert('Payment complete with id ' + paymentId)
},
// 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) {
alert(error.message)
},
// This is called just before the activation request is sent.
onActivating: function () {
console.log('Activating PINPad...')
},
// This is called when the pin pad is successfully activated.
onActivate: function () {
console.log('PINPad activated')
},
// This is called just before the cancellation request is sent.
onCancelling: function () {
console.log('Cancelling activation...')
},
// This is called when the activation is successfully cancelled.
onCancel: function () {
console.log('Activation cancelled')
},
// This is called if the cancellation request fails.
onCancelFailure: function (error) {
console.log('Cancellation failed:', error.message)
},
})For the Pin Pad Cloud Checkout Widget
Call PPCDirect.attach() on your site and pass the parameters documented below.
PPCDirect.attach({
// An HTML selector for the element where you want to render the PPC Direct Widget
// widget on your site:
elementSelector: '#gsg-widget',
// The id of the cart to be checked out using the PPC Direct Widget.
cartId: ‘4ed4137c-3d89-44ad-92a1-c9f3e916f51e',
// The OAuth token to be used for requests to GSGPay
jwt: '',
// Use 'demo' in your non-production environment to use test data.
// Use 'prod' in your production environment to use real data.
environment: 'beta',
// This is called when the payment is completed.
onSuccess: function (paymentId) {
alert('Payment complete with id ' + paymentId)
},
// 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) {
alert(error.message)
},
// This is called just before the activation request is sent.
onActivating: function () {
console.log('Activating PINPad...')
},
// This is called when the pin pad is successfully activated.
onActivate: function () {
console.log('PINPad activated')
},
})When the JavaScript is executed, the widget loads and the cashier will select the tender being used and activate the PIN pad, allowing the customer to complete payment at the PIN Pad.
The widget will also handle polling the PIN pad for the transaction status. When the widget receives a terminal status, the onSuccess and onError events will be triggered.
Updated 2 days ago
