Skip to main content

Core concepts

In-Store Payments provides a simplified, single-source solution for point-of-sale (POS) payment processing with the following key identifiers and API functionality.

Key identifiers

The following key identifiers are essential to POS payment processing using our In-Store Payments API. Use the following fields to identify the transaction type and amount and retrieve payment transaction details.

Values assigned by the In-Store Payments API

transactionIdentifier

A value in transactionIdentifier indicates a processed POS payment transaction. Use transactionIdentifier to retrieve payment transactions by reference.

cardToken

The Payment Terminal Application returns a cardToken as a credential in place of card data for future card-on-file transactions.

Values assigned by you

operation

operation helps identify what type of transaction is being performed.

type

type sets the type of transaction operation (for example, refund or void). 

requestedAmount

requestedAmount identifies the amount of the POS payment transaction.

uniqueTransactionID

Provide a uniqueTransactionID for customer-defined data in reporting. The uniqueTransactionID is an optional value.

reference

Generate and send a unique reference value for each request. reference is a 15 character alphanumeric field.

invoice

invoice is a 6 character alphanumeric field for the transaction invoice number.

API functionality

Connectivity

Your POS application is expected to maintain an open connection throughout each operation (simple or complex). Between operations, disconnect and reconnect as needed. Our Payment Terminal Application supports TCP/IP communication.

If connectivity is lost, the Payment Terminal Application cancels complex operations and returns to the idle screen. For a Transaction operation, the following two cases apply:

  • If the connection to the POS Application is lost before the Payment Terminal Application begins to communicate with our payment host, the Transaction operation is canceled, and the Payment Terminal Application returns to the idle screen.
  • If the connection to the POS Application is lost after or during the Payment Terminal Application communication with our payment host, the Payment Terminal Application automatically reverses the transaction (if approved), then returns to the idle screen.
Tip

To detect a connection loss, listen to the relevant WebSocket events that signal error conditions.

Message format

The Payment Terminal Application supports JSON messages over WebSocket using a persistent connection. If the connection is lost, your POS application resumes the connection.

Escape the following JSON characters when used in a string:

  • Replace newline with \n (which includes a carriage return)
  • Replace tab with \t
  • Replace double quote with \”
  • Replace backslash with \\
  • Backspace, Form feed, and other standard JSON escape sequences are not supported
Note

JSON data is case sensitive.

Security

Communication between your POS Client application and the Payment Terminal Application is secured by TLS. We support mutual authentication by using certificates on both the Payment Terminal Application and POS sides.

Environments

Our client testing and production environments are available 24/7 with 99.99%+ uptime.