Embedded In Person Checkout

Embedded In Person Checkout is a powerful way to integrate our payment processing capabilities into your software. We offer two styles of embedded integration to make this experience as seamless as possible for you and your cashiers - one using our Embedded In Person Checkout Widget, and the other with direct integration to our PIN pad APIs. The business and technical flow of how an Embedded In Person Checkout works is outlined below.

Step 1: Create a Cart to Pay

With a customer present with your cashier, and a cashiering station with PIN pad available to the cashier, 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. The URL for this request will differ based on which integration style you choose.

{
    "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 get a JSON response formatted like below.

{
  "cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
  "fees": {
    "CreditCard": {
      "primary": "1257.38",
      "fee": "1.23",
      "total": "1258.61",
    },
    "DebitCard": {
      "primary": "1257.38",
      "fee": "1.23",
      "total": "1258.61",
    },
    "ECheck": {
      "primary": "1257.38",
      "fee": "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: Activate the PIN Pad

When the customer is ready to make payment, you will make a PIN Pad activation request to the local Grant Street Windows Application which is connected to the PIN Pad to request activation of the PIN Pad for the cart that was just created. This is a simple API call of the form:

POST /api/v1/pay/inperson/carts/{cartId}/activation

{
  "tenderType": "CreditCard" 
}

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.

Step 3: Monitor the Transaction Status

Upon success status from the activation, the transaction is in the hands of the customer at the PIN pad. This could take an indeterminate amount of time, so during this process you can poll the Grant Street Windows Application for the status of the transaction. This is a simple GET request that will return you the current state of the transaction, beginning with updates on what the customer is doing and/or the state of the PIN pad, and ending in either cancelation of the transaction by the customer or a paid status.

GET /api/v1/pay/inperson/carts/{cartId}/activation

The return status at any point prior to the successful conclusion of the transaction will look similar to:

{
  "status": "waiting",
  "message": "Waiting for customer to present card."
}

📘

De-Activating a PIN Pad

If for some reason the cashier needs to deactivate the PIN pad and stop processing of the transaction (for example because the customer walked away), our API is able to 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 (/api/v1/pay/inperson/carts/{cartId}/activation on the GWA API instance, as noted in our API reference.

This request can be resent as often as every half second (500ms) to keep the cashier aware of the status and to inform your system of the conclusion of the transaction. At the point at which the payment has been processed, this API endpoint will return a "paid" status, which will also include the payment identifier for the payment which completed the transaction, such as below.

{
  "status": "paid",
  "message": "The transaction is complete.",
  "payment": {
    "paymentId": "Z8903248606"
  }
}

At this point, the transaction has been completed, the customer has been successfully charged, and you can record this payment identifier in your system of record. More information on the cart status endpoint is available in our detailed API reference.

Step 4: Retrieve Payment Details

If you would like to record additional payment details in your system, and/or provide payment information on a receipt, you may do so by looking at this payment using one of our payment information API endpoints.