# Overview

The S4/.Net 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](/apis/payments-platform-rest/openapi)) 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/.Net component requires .Net Framework version 6.0 or higher on Windows. If there is a need for compatibility with earlier versions of the .Net Framework, 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.

# SDK & Sample Application

| 
| Description | Version | File |
| .Net SDK File | 1.0.0 | [S4RestAPI.dll](/assets/s4restapi.fbc77b3a7e7d5a6cbab43727d140d865f8210ab5f1dcbca19af912c37497c389.86dce026.dll) |
| .Net Sample Project | 1.0.0 | [S4DotNetSample.zip](/assets/s4dotnetsample.4dfaa4b756166562632cc473fdc4f34159cde226812289f6d00bd1bf8a631e36.86dce026.zip) |


# API Description

S4/.Net 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.  It works similar to a .Net ExpandoObject
- **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


# 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/.Net (Windows)

To install S4 /.Net, you first need to install the .Net framework version 6.0 or higher. Please refer to https://learn.microsoft.com/en-us/dotnet/framework/install/ for install instructions.

Confirm that you have received the S4/.Net Windows DLL. This should have been provided to you by your Integration Analyst prior to the integration project kick-off meeting. The DLL can be dropped into your .Net project root directory.

In addition, you’ll need to use NuGet packages to add a package to your project

- In your visual studio project, right click on your solution
- Select Manage NuGet Packages
- Install Newtonsoft.Json


# 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


```
using S4RestAPI;

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",    "RestAPIDotNetSdk");
s4Request.SetHeader("CompanyName",      "Shift4");
s4Request.SetHeader("AccessToken",      ""); //PROVIDED BY SHIFT4

dynamic dRequest = new S4DynamicObject();

dRequest.dateTime = DateTime.Now.ToString("o");

dRequest.amount = new S4DynamicObject();
dRequest.amount.tax = 1.00;
dRequest.amount.total = 11.00;

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

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

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

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

dRequest.customer = new S4DynamicObject();

dRequest.postalCode = "89000";


s4Request.SetRequest(dRequest);
Console.WriteLine("Processing Transaction");
S4Response s4Response = s4Request.Process();
dynamic resultObj = s4Response.GetResponse();
if (s4Response.GetHttpStatusCode() == 200)
{
    if (resultObj.IsSet("result[0].transaction.responseCode"))
        Console.WriteLine("Response Code:" + resultObj.result[0].transaction.responseCode);
    if (resultObj.IsSet("result[0].transaction.authorizationCode"))
        Console.WriteLine("Authorization Code:" + resultObj.result[0].transaction.authorizationCode);
}
else
{
    Console.WriteLine("Error:" + s4Response.GetHttpStatusCode());
    Console.WriteLine("Error Response:" + resultObj.ToLog());
    if (s4Response.GetRequiresAudit())
    {
        Console.WriteLine("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
    }
}

Console.WriteLine("Complete");
```

# Static Class Definitions

## 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 |
| Parameters | None |
| Results | S4DynamicObject instance |
| Description | S4DynamicObject is a class that is used for setting requests and receiving responses. It can be used to dynamically access and/or set properties.   It offers similar functionality to an ExpandoObject with one major difference: If you access a property that does not exist, then a blank value will be returned |


## 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](/sdks/dotnet#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](/apis/payments-platform-rest/openapi/transactions/transactionsauthorization) 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](/apis/payments-platform-rest/openapi/transactions/transactionsauthorization),  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](/guides/response-handling/timeouts-and-communications-failures#logging-communication-failures-for-auditor-review) 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.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](/guides/quickstart#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](/apis/payments-platform-rest/openapi/transactions/transactionsauthorization) 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 configurationAll 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](/guides/quickstart#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](/apis/payments-platform-rest/openapi/transactions/transactionsauthorization) would use `api/rest/v1/transactions/authorization` |


# Technical Considerations

## Threading

The S4/.Net 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