Embedded In-Person Direct Integration
If your application is not using the checkout widget, your cashiering application may use the cashier’s local Grant Street Windows Application (GWA) at http://127.0.0.1:47251/ for interactions with the PIN pad or our API endpoints for the PIN Pad Cloud Direct Integration.
- For solutions that are using GWA your cashiering application will utilize the same endpoint for both non-production and production environments.
- Different PIN Pads must be used for non-production and production environments.
The endpoints will look like the following:
| Function | HTTP Method | GWA Direct Integration | Pin Pad Cloud Direct Integration |
|---|---|---|---|
| PIN Pad Activation | POST | http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation | https://{env}.gsg.tech/api/v1/pay/inperson/carts/{cartId}/activation |
| Embedded In-Person PINPad Activation Status Request | GET | http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation | https://{env}.gsg.tech/api/v1/pay/inperson/carts/{cartId}/activation |
| Cancel Embedded In-Person Creation | DELETE | http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation | Unavailable |
Step 1: Cashier Determines the Items to Pay for
With a customer present and working with a cashier, your application will need a method to determine what customers will pay for, allowing the cashier to select and create item(s) in a cart. Once the cashier determines the items, it must communicate them through your application 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 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/inperson/carts” URL, where “env” is either “beta,” “demo,” or “www” for production.
{
"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.
Step 3: Store identifier and prepare for the Embedded Checkout
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.
Example Successful Response
{
"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"
}
}
}Step 4: Activate the PIN Pad
When the customer is ready to make a payment, you will make a PIN pad activation request. This is a simple API call of the form:
For Grant Street Windows Application
POST http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation
This request will instruct the Grant Street Windows Application to activate the PIN pad to take payment for the total amount of the cart provided. More details on the Cart Activation endpoint are available in our detailed API reference for PIN pad Activation.
For the Pin Pad Cloud Direct Integration
POST https://{env}.gsg.tech/api/v1/pay/inperson/carts/{cartId}/activation
For the Pin Pad Cloud Direct integration, include the unique PIN pad serial number found on your device in the body of your activation response as seen in the example below.
{
"tenderType":"CreditCard"
"pinpadReference":"123456789"
}Step 6: Monitor the Transaction Status
Upon receiving a successful status from the activation, the transaction is in the customer's hands at the PIN pad. This process may take an indeterminate amount of time. During this time, you can poll the PIN pad for the transaction status. This is a simple GET request that returns the current state of the transaction, starting with updates on the customer's actions and/or the PIN pad status, and concluding with either the transaction being canceled by the customer or a paid status.
For Grant Street Windows Application
GET http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation
For the Pin Pad Cloud Direct Integration
GET https://{env}.gsg.tech/api/v1/pay/inperson/carts/{cartId}/activation
The return status at any point before the successful conclusion of the transaction will look similar to:
{
"status": "waitForCard",
"message": "Waiting for customer to present card."
}This request can be resent as often as every half second (500ms) to keep the cashier informed of the status and to notify your system of the transaction's conclusion. Once the payment has been processed, this API endpoint will return a payment approved status, which will also include the payment identifier for the completed transaction, as shown:
{
"status": "paymentApproved",
"message": "The transaction is complete.",
"payment": {
"paymentId": "Z8903248606"
}
}At this point, the transaction has been completed, PaymentExpress has successfully charged the customer, and you can record this payment identifier in your system of record. For more information on the cart status endpoint, refer to our detailed API reference.
Status Responses
The exact status responses that you may receive will depend on if you are using GWA or the Pin Pad Cloud Direct solution. The following tables lists all of the possible values for the “status” field in the PINPad Activation Request response for each integration:
For Grant Street Windows Application
| Status | Sample Message |
|---|---|
| Cancelled | "The customer canceled the transaction." |
| CardNotSupported | "This card is not supported. Please try again with a different card." |
| CardReadError | "The chip could not be read. Please remove card." |
| Created | “Cart created. Waiting on activation.” |
| EMVFallback | "Insert or tap failed. Please swipe card." |
| Expired | "Cart expired. Terminal cannot be activated for this cart." |
| InternalError | "Something went wrong." |
| PaymentApproved | “The transaction is complete.” |
| PaymentDeclined | "Payment declined" or a message with additional information provided by the processor |
| PinpadError | "The terminal is not configured correctly." |
| Processing | "Processing..." or a message with more details |
| WaitForCard | "Waiting for card." |
| WaitForCardRemoved | "Waiting for customer to remove card." |
| WaitForPIN | "Waiting for customer to enter PIN." |
| PaymentApproved | "The payment was approved" |
For the Pin Pad Cloud Direct Integration
| Status | Sample Message |
|---|---|
| created | Activation request accepted |
| processing | “Processing…” or a message with more details |
| payment_approved | “The payment was approved” |
| payment_declined | “Payment declined” or a message with additional information provided by the processor. |
| internal_error | “Something went wrong.” |
Deactivating a PIN Pad
If you are using a Grant Street Windows Application (GWA) PIN pad and the cashier needs to deactivate the PIN pad and stop processing the transaction (for example, because the customer has walked away), our API can support this right up until the moment the card has been presented for payment.
To do so, simply send a DELETE request to the PIN pad activation URL:
DELETE http://127.0.0.1:47251/api/v1/pay/inperson/carts/{cartId}/activation
If you are not using GWA PIN pads for your integration, the cashier will need to physically click the “Cancel” or “NO” button on the PIN pads.
Step 7: Retrieve Payment Details
If you would like to record additional payment details in your system and/or provide payment information on a receipt, you can do so by accessing this payment using one of our payment information API endpoints.
Updated 2 days ago
