Overview
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

The S4/Java SDK is a wrapper around the Shift4 REST API (Shift4 Gateway API). The Shift4 REST API is an http based API.

As an integrator, you can integrate directly to the Shift4 REST API
Or, you can use the SDK, which simplifies and abstracts many of the complexities of the REST API
- As a wrapper, please note the following
  - You’ll still refer to the core REST API documentation (Shift4 Gateway API) for details on the transaction types, fields and all other details
  - The SDK allows you to build requests and receive responses. Using the SDK, you’ll control the following aspects:
    - The HTTP headers
    - The HTTP body
    - The HTTP type (POST, GET, etc)
  - Some of the areas of the REST API that are simplified or eliminated are:
    - The underlying http communication
      - The SDK will handle http communication automatically
    - Timeout and communication failure handling
      - The SDK will handle timeouts and communication failures automatically
    - Logging and log masking
      - The SDK will log requests/responses and will mask sensitive data

The S4/Java component requires Java 1.8, and it will work on many environments that support Java including Windows, Linux and Android.

If there is a need for compatibility with earlier versions of the Java SDK, please contact your Shift4 Integration Analyst for review. If you do not already have an Shift4 Integration Analyst assigned, one will be assigned to you during project kickoff.

Sample Applications

Three sample applications are available. Reach out to your API Analyst to obtain the latest sample application.

Simple Command Line

A simple command line application is the fastest way to get started. Your Shift4 integration analyst can provide the sample files

To compile:
- javac -cp S4RestAPI.jar S4JavaSample.java
To execute:
- Windows: java -cp S4RestAPI.jar;. S4JavaSample
- Linux: java -cp S4RestAPI.jar:. S4JavaSample

Android/Java

A sample java application can be used to get started with android/java development. Your Shift4 integration analyst can provide the sample project files. Open the project in Android studio and compile

Android/Kotlin

A sample kotlin application can be used to get started with android/kotlin development. Your Shift4 integration analyst can provide the sample project files. Open the project in Android studio and compile

API Description

S4/Java is comprised of the following classes, all of which are located in the namespace S4RestAPI:

S4Request: This class is used to setup a request
S4Response: This is the class that represents a response
S4DynamicObject: this class is used to represent a JSON like structure.
S4Mode: this class has defines that instruct the API on which processing mode is being used
S4Method: this class has defines that instruct the API on which http method is being used on the underlying request to Shift4
S4Type: this class has defines data types that are available in an S4DynamicObject

Expected Flow

The following outlines the steps to process a transaction

Step 1: Construct

The first step is to construct an S4Request object. You must construct a new object for every request

Step 2: SetConfig

The next step is to set some configuration parameters such as the endpoint, and the processing mode

Step 3: SetHeaders

Next, you’ll set the http headers as needed for your REST (Shift4 Gateway API ) request

Step 4: SetRequest

The developer must then build a request object, and populate it with all of the structured data fields required for the request. When the request object is built, the developer calls SetRequest

Step 5: Process

Next, call the Process() method. The Process() method blocks until the transaction is completely processed. Process with return an S4Response object

Step 6: Response Handling

The developer then calls GetHttpStatusCode() to confirm the http result and GetResponse() to retrieve a response object. This object contains all of the response fields. At this stage the response can be handled and processed in your integration layer

Installing S4/Java

To install S4/Java, you first need to install the Java version 1.8 or higher.

Confirm that you have received the S4/Java jar file. This should have been provided to you by your Integration Analyst prior to the integration project kick-off meeting. The Jar file can be dropped anywhere into your classpath

Running as a Windows Service

If you are running your application as a windows service, please note the following

The LogPath will also need to be defined as a folder that the client application has permission to write to. LogPath can be updated with a SetConfig call

Sample Code

import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

import com.shift4.s4restapi.*;

public class S4JavaSample {
	public static void main(String[] args) {
		S4Request s4Request = new S4Request();

		s4Request.SetConfig("Mode", S4Mode.HOST_DIRECT);
		s4Request.SetConfig("Method", S4Method.POST);
		s4Request.SetConfig("Host", "https://api.shift4test.com");
		s4Request.SetConfig("URLPath", "/api/rest/v1/transactions/sale");

		s4Request.SetHeader("InterfaceVersion", "2.1");
		s4Request.SetHeader("InterfaceName", "RestAPIJavaSdk");
		s4Request.SetHeader("CompanyName", "Shift4");
		s4Request.SetHeader("AccessToken", "29CEDBCC-CC87-4AEF-B698-80296C52D9EF");

		S4DynamicObject dRequest = new S4DynamicObject();

		String formattedDateTime = ZonedDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSXXX"));

		dRequest.SetValue("dateTime", formattedDateTime);
		S4DynamicObject amount = new S4DynamicObject();
		amount.SetValue("tax",      1.00);
		amount.SetValue("total",    11.00);
		dRequest.SetValue("amount", amount);

		S4DynamicObject[] apiOptions = new S4DynamicObject[1];
		apiOptions[0] = new S4DynamicObject();
		apiOptions[0].SetValue("ALLOWPARTIALAUTH");
		dRequest.SetValue("apiOptions", apiOptions);

		S4DynamicObject clerk = new S4DynamicObject();
		clerk.SetValue("numericId", "12345");
		dRequest.SetValue("clerk", clerk);

		S4DynamicObject transaction = new S4DynamicObject();
		transaction.SetValue("invoice", "6820973");
		dRequest.SetValue("transaction", transaction);

		S4DynamicObject card = new S4DynamicObject();
		card.SetValue("entryMode",       "M");
		card.SetValue("number",          "4444333322221111");
		card.SetValue("expirationDate",  1229);
		
		S4DynamicObject securityCode = new S4DynamicObject();
		securityCode.SetValue("indicator", "1");
		securityCode.SetValue("value",     "333");
		card.SetValue("securityCode", securityCode);
		dRequest.SetValue("card", card);

		S4DynamicObject customer = new S4DynamicObject();
		customer.SetValue("postalCode", "89000");
		dRequest.SetValue("customer",   customer);

		s4Request.SetRequest(dRequest);
		System.out.println("Processing Transaction");
		S4Response s4Response = s4Request.Process();
		S4DynamicObject resultObj = s4Response.GetResponse();
		if (s4Response.GetHttpStatusCode() == 200)
		{
			if (resultObj.IsSet("result[0].transaction.responseCode"))
				System.out.println("Response Code:" + resultObj.GetArray("result")[0].GetObject("transaction").GetString("responseCode"));
			if (resultObj.IsSet("result[0].transaction.authorizationCode"))
				System.out.println("Response Code:" + resultObj.GetArray("result")[0].GetObject("transaction").GetString("authorizationCode"));
		}
		else
		{
			System.out.println("Error:" + s4Response.GetHttpStatusCode());
			System.out.println("Error Response:" + resultObj.ToLog());

			if (s4Response.GetRequiresAudit())
			{
				System.out.println("Transaction Requires Audit");
				//Developer needs to add this transaction to a list that requires manual audit
				//See https://myportal.shift4.com/index.cfm?action=development.shift4api#section/Logging-Communication-Failures-for-Auditor-Review
			}
		}

		System.out.println("Complete");
	}
}

Static Class Definitions

S4Type

S4Type is used to define data types contained in a S4DynamicObject

S4Type.STRING: string value
S4Type.OBJECT: object value
S4Type.ARRAY: array value
S4Type.FLOAT: double (float) value
S4Type.INTEGER: int value

S4Mode

S4Mode is used to control the transaction processing mode

S4Mode.COM_ENG: commerce engine. Used when processing direct to commerce engine on premises
S4Mode.COM_ENG_CLOUD: Commerce engine cloud. Used when processing via commerce engine cloud
S4Mode.HOST_DIRECT: Host direct. Used when processing direct to the Shift4 cloud endpoint

S4Method

S4Method is used to control the http method used to process a transaction.

S4Method.DELETE: http delete
S4Method.POST: http post
S4Method.GET: http get

S4LogVerbosity

S4LogVerbosity is used to control the log verbosity

S4LogVerbosity.Info: highest level of logging
S4LogVerbosity.Warning: log warnings and errors
S4LogVerbosity.Error: log errors only

Constructor Definitions

S4DynamicObject

Constructor Syntax	S4DynamicObject() S4DynamicObject(String JSON)
Parameters	String JSON a string representing JSON that can be used to initialize an S4DynamicObject
Results	S4DynamicObject instance
Description	S4DynamicObject is a class that is used for setting requests and receiving responses. It can be used to access and/or set properties.

S4Request

Constructor Syntax	S4Request()
Parameters	None
Results	S4Request instance
Description	S4Request is a class that is used to build and process a request

S4Response

Constructor Syntax	S4Response
Parameters	None
Results	S4Response instance
Description	S4Response is a class that represents a response. An S4Response is returned when calling S4Request.Process().

Method Definitions

S4Request.SetConfig

Method Syntax	void SetConfig(String FieldName, String FieldValue) void SetConfig(String FieldName, S4Mode mode) void SetConfig(String FieldName, S4Method method) void SetConfig(String FieldName, S4LogVerbosity logVerbosity)
Parameters	String FieldName configuration name String FieldValue configuration value S4Mode mode processing mode S4Method processing method S4LogVerbosity log verbosity
Results	None
Description	Used to set configuration for a request. For a list of configuration values, see Configuration Options below. This function must be called once for each configuration that is being set.set.
Exceptions	None

S4Request.SetHeader

Method Syntax	void SetHeader(String FieldName, String FieldValue)
Parameters	String FieldName header name String FieldValue header value
Results	None
Description	This function is used to specify the http headers in the request. For example, an Authorization requires 4 headers: `InterfaceVersion`, `InterfaceName`, `CompanyName` and `AccessToken`. To perform this transaction, you would call `SetHeader` 4 times, once for each header.
Exceptions	None

S4Request.SetRequest

Method Syntax	void SetRequest(S4DynamicObject request) void SetRequest(String json)
Parameters	S4DynamicObject request request is the object that contains the request structure. String json json body of the request
Results	None
Description	This function is used to specify the body of the request. The body must match the JSON fields indicated in the REST API for the request that you are processing
Exceptions	None

S4Request.Process

Method Syntax	S4Response = S4Request.Process()
Parameters	None
Results	Returns an S4Response object that represents the response
Description	This function is used to process a request. This call is a blocking call
Exceptions	None

S4Response.GetHttpStatusCode

Method Syntax	int GetHttpStatusCode()
Parameters	None
Results	Returns an integer representing the http response code 200 is a normal/valid response anything else is considered an error
Description	This function is used to obtain the http response code of the request. For example for an Authorization, you might get 200 for a valid response 4xx or 5xx for an error
Exceptions	None

S4Response.GetHttpError

Method Syntax	string GetHttpError()
Parameters	None
Results	Returns an error string representing the http error
Description	This function is used to obtain the http error string. This can be used when GetHttpStatusCode returns a value other than 200
Exceptions	None

S4Response.GetRequiresAudit

Method Syntax	bool GetRequiresAudit
Parameters	None
Results	Returns a boolean indicating if the request requires an audit
Description	As noted in the Handling Response guide, certain transactions may need to be recorded for manual review to determine if they processed not. While it’s rare that a transaction requires manual review, it can happen. This function call can be used to determine if manual review/audit is required. Note that when GetHttpStatusCode returns a 200 (indicating a valid response), GetRequiresAudit does not need to be checked.
Exceptions	None

S4Response.GetResponse

Method Syntax	S4DynamicObject GetResponse()
Parameters	None
Results	Returns a S4DynamicObject representing the JSON response
Description	This function is used to obtain an object representing the JSON response.
Exceptions	None

S4Response.GetHeaders

Method Syntax	S4DynamicObject GetHeaders()
Parameters	None
Results	Returns a S4DynamicObject representing the http response headers
Description	This function is used to obtain the http response headers of the transaction
Exceptions	None

S4DynamicObject.IsSet

Method Syntax	IsSet(String path)
Parameters	String path this is the path that you want to check if it’s set
Results	Returns a boolean indicating if the path exists or not
Description	This function can be used to determine if a field is set in a S4DynamicObject variable. Example: IsSet("result[0].transaction.responseCode")
Exceptions	None

S4DynamicObject.ToLog

Method Syntax	String ToLog()
Parameters	None
Results	Returns a string that has sensitive fields masked and is safe to be written to a log file.
Description	Requests and responses may contain sensitive data that cannot be written to disk such as the credit card number and the credit card CVV. This function returns a string representing the response, but with sensitive fields masked out.
Exceptions	None

S4DynamicObject.GetString

Method Syntax	String GetString() String GetString(String Key)
Parameters	String key object index
Results	Returns a string representing the value in the S4DynamicObject. When called with a Key, it will return the value in the index noted by the Key
Description	GetString is used to obtain a value from an S4DynamicObject. Type conversion will be handled automatically in the API call. Ex: an integer value will be converted to a string
Exceptions	None

S4DynamicObject.GetInteger

Method Syntax	int GetInteger() int GetInteger(String Key)
Parameters	String key object index
Results	Returns an integer representing the value in the S4DynamicObject. When called with a Key, it will return the value in the index noted by the Key
Description	GetInteger is used to obtain a value from an S4DynamicObject. Type conversion will be handled automatically in the API call. Ex: a string value will be converted to an integer
Exceptions	None

S4DynamicObject.GetFloat

Method Syntax	double GetFloat() double GetFloat(String Key)
Parameters	String key object index
Results	Returns a double representing the value in the S4DynamicObject. When called with a Key, it will return the value in the index noted by the Key
Description	GetFloat is used to obtain a value from an S4DynamicObject. Type conversion will be handled automatically in the API call. Ex: a string value will be converted to a double
Exceptions	None

S4DynamicObject.GetObject

Method Syntax	S4DynamicObject GetObject() S4DynamicObject GetObject(String Key)
Parameters	String key object index
Results	Returns an object representing the value in the S4DynamicObject. When called with a Key, it will return the value in the index noted by the Key
Description	GetObject is used to obtain a sub object in an S4DynamicObject. If the value isn’t inherently a object, then an empty S4DynamicObject will be returned instead.
Exceptions	None

S4DynamicObject.GetArray

Method Syntax	S4DynamicObject[] GetArray() S4DynamicObject[] GetArray(String Key)
Parameters	String key object index
Results	Returns an array of S4DynamicObject. When called with a Key, it will return array based on the value in the Key
Description	GetArray is used to obtain an array of S4DynamicObjects. If the value isn’t inherently an array, then an empty S4DynamicObject array will be returned instead.
Exceptions	None

S4DynamicObject.GetType

Method Syntax	S4Type GetType() S4Type GetType(String key)
Parameters	String key object index
Results	Returns an S4Type indicating the data type contained in the S4DynamicObject
Description	GetType can be used to obtain the underlying data type contained in a S4DynamicObject
Exceptions	None

S4DynamicObject.SetValue

Method Syntax	void SetValue(String key, String value) void SetValue(String key, int value) void SetValue(String key, double value) void SetValue(String key, S4DynamicObject value) void SetValue(String key, S4DynamicObject value[]) void SetValue(String value) void SetValue(int value) void SetValue(double value) void SetValue(S4DynamicObject value) void SetValue(S4DynamicObject value[])
Parameters	String key object index String value the string value to set int value the integer value to set double value the double value to set S4DynamicObject value the S4DynamicObject value to set S4DynamicObject[] value the array of S4DynamicObject values to set
Results	None
Description	SetValue is used to set value in an S4DynamicObject. When setting a Key/Value pair, use one of the function signatures with a key and value. When setting just a value, use one of the function signatures with just a value
Exceptions	None

S4DynamicObject.ToJson

Method Syntax	String ToJson()
Parameters	None
Results	Returns a string representing the JSON response
Description	This function returns a string representing the response. It returns a value similar to the ToLog function, but sensitive fields are not masked out.
Exceptions	None

Configuration Options

Mode

Parameter Name	Mode
Mandatory/Optional	Mandatory
Description	This is a configuration that instructs the API on how it’s processing the transaction. Options are: S4Mode.HOST_DIRECT: this mode is used when you need to send requests directly to the Shift4 host S4Mode.COM_ENG: this mode is used when you need to send requests to commerce engine on premise S4Mode.COM_ENG_CLOUD: this mode is used when you are sending requests to commerce engine cloud

Host

Parameter Name	Host
Mandatory/Optional	Mandatory
Description	This is used to specify the host that the API will connect to. See Quick Start URLs for a list of potential values to use for the host. Example: for host direct, you would use Test: `https://api.shift4test.com/api/rest/v1` Production: `https://api.shift4api.net/api/rest/v1`

Method

Parameter Name	Method
Mandatory/Optional	Mandatory
Description	This is used to specify the the http method for the transaction request that you are performing `S4Method.GET`: process the request using http GET `S4Method.POST`: process the request using http POST `S4Method.DELETE`: process the request using http DELETE This will match the http method specified in the REST API. For example, an Authorization would use `S4Method.POST`

LogEnabled

Parameter Name	LogEnabled
Mandatory/Optional	Optional
Description	By default, the API will record API activity to log file. It’s recommended to always leave this on. To disable logging, set LogEnabled to “N” To enable logging, set LogEnabled to “Y”

LogVerbosity

Parameter Name	LogVerbosity
Mandatory/Optional	Optional
Description	By default, the API will record API activity to log file with a log verbosity of `Info`. LogVerbosity can be adjusted with this configuration All logging in the SDK is done at one of the three levels S4LogVerbosity.Info S4LogVerbosity.Warning S4LogVerbosity.Error It’s recommended to keep LogVerbosity at the default level

LogPath

Parameter Name	LogPath
Mandatory/Optional	Optional
Description	By default, the API will record API activity to log file in the local directory of the application that is running. This configuration can be used to change the log file path

Port

Parameter Name	Port
Mandatory/Optional	Optional
Description	This is used to specify the port that the API will connect to. See Quick Start URLs for a list of potential values to use for the host port. Host Direct: 443 Commerce Engine For Cloud: 443 Commerce Engine For On Premise: 8085 Default value is 443.

Timeout

Parameter Name	Timeout
Mandatory/Optional	Optional
Description	This is used to set the request timeout value in seconds. It is not recommended to adjust this configuration. Default value is 65

URLPath

Parameter Name	URLPath
Mandatory/Optional	Optional
Description	This is used to specify the the URL path for the request that you are performing This will match the url path specified in the REST API. For example, an Authorization would use `api/rest/v1/transactions/authorization`

Technical Considerations

Threading

The S4/Java library supports a multi-threaded environment. However, each instance (object) of the API can only be used in one thread at a time. You cannot share an object concurrently between different threads at the same time. In practical terms, this means that a program must complete a request in one thread without using the same object in a different thread. Objects should be created and then discarded after each request

Android Considerations

The following are specific notes if you are developing an integration on andriod

You’ll need to ensure that your application has the android.permission.INTERNET permission
For logging, set the log path to the apps private storage path
- ex: context.getFilesDir().getPath() + "/S4RestAPI.log"

OverviewCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude