# Overview

The S4/Apple 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/Apple component requires iOS 15.6 or macOS 11.5 minimum. (Swift/Objective-C, Apple ARM, and Intel).

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


# SDK & Sample Application

| 
| Description | Version | File |
| Apple SDK Framework File | 1.20 | [AppleSDK.zip](/assets/applesdk.952ea515f1f9ce149f023fe70f583d4eb2b3a0283fcf78c18b414ec104f4e4f3.35aab9b4.zip) |
| iOS Sample App | 1.0 | [iOSSampleApp.zip](/assets/iossampleapp.69a16c0c21b4d463901bd48f807b7da19b62c2dbcc2acaa835014463bd8562f2.35aab9b4.zip) |
| Mac Sample App | 1.0 | [macOSSampleApp.zip](/assets/macossampleapp.c892e499e85e26eb8b15e375e29df25f039bc71057fe8b32f8b36e6b8603e0a7.35aab9b4.zip) |


The sample iOS, and MacOS applications can be used to demonstrate usage, and get started with development. Download the sample app .zip release above, and extract this package. Drop the sample src file into a new xcode project and compile.

# API Description

S4/Apple 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
- **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 init an S4Request object. You must init a new object for every request.

## Step 2: setConfig

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

## Step 3: setHeaders

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

## Step 4: setRequest

The developer must then build up an NSDictionary 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 and passes it the dictionary object.

## Step 5: process

Next, call the process method. It is an async method. Provide it an anonymous callback method as an argument. **Make sure this callback has `S4Response` object as the only argument.** This callback will be called when the transaction is completely processed and the response is available. The developer does not need to init an `S4Response` object. The process method will automatically attach the `S4Response` object to the anonymous callback.

## 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/Apple SDK

This SDK is provided in the form of a single .xcframework file folder. It is compatible with macOS, and iOS. Confirm that you have received the S4/.xcframework file. This should have been provided to you by your Integration Analyst prior to the integration project kick-off meeting.

## Xcode

1. Drop the .xcframework file folder into your Xcode project.
2. Add the framework as an asset in your project settings (Project → Targets → General → Frameworks, Libraries, and Embedded Content → Embed and Sign).
3. Enable outgoing, incoming network capability.


## Minimum Framework OS Compatibility

- **macOS**: Big Sur 11.5 or later
- **iOS**: iOS 15.6 or later
- Apple ARM, and Intel


# Sample Code


```
#import <Shift4RestAPISDK/Shift4RestAPISDK.h>

S4Request *s4Request = [[S4Request alloc] init];

[s4Request setConfig:@"Mode" mode:S4ModeHostDirect];
[s4Request setConfig:@"Method" method:S4MethodPOST];
[s4Request setConfig:@"Host" fieldValue:@"https://api.shift4test.com"]; // test environment, use https://api.shift4api.net/api/rest/v1 for production.
[s4Request setConfig:@"URLPath" fieldValue:@"/api/rest/v1/transactions/sale"];

[s4Request setHeader:@"InterfaceVersion" fieldValue:@"2.1"];
[s4Request setHeader:@"InterfaceName" fieldValue:@"RestAPIObjectiveCSdk"];
[s4Request setHeader:@"CompanyName" fieldValue:@"Shift4"];
[s4Request setHeader:@"AccessToken" fieldValue:@""]; //PROVIDED BY SHIFT4

NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
[dateFormatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ"];

[s4Request setRequest: @{
    @"amount": @{
        @"tax": @"1.00",
        @"total": @"11.00",
    },
    @"dateTime": [dateFormatter stringFromDate:[NSDate date]],
    @"transaction": @{
        @"invoice": @"6820973"
    },
    @"card": @{
        @"entryMode": @"M",
        @"number": @"4444333322221111",
        @"expirationDate": @"1229",
        @"securityCode": @{
          @"indicator": @"1",
          @"value": @"333"
        }
    },
    @"customer": @{},
    @"postalCode": @"89000"
}];

NSLog(@"Processing Transaction");

[s4Request process:^(S4Response *s4Response) {
    // Process complete async callback
    NSLog(@"Completed Transaction");
    if ([s4Response getHttpStatusCode] == 200) {
        NSDictionary *responseData = [s4Response getResponse];
        if (responseData[@"result"][0][@"transaction"][@"responseCode"] != nil) {
            NSLog(@"Response Code: %@", responseData[@"result"][0][@"transaction"][@"responseCode"]);
        }
        if (responseData[@"result"][0][@"transaction"][@"authorizationCode"] != nil) {
            NSLog(@"Authorization Code: %@", responseData[@"result"][0][@"transaction"][@"authorizationCode"]);
        }
    } else {
        NSLog(@"Error: %ld", [s4Response getHttpStatusCode]);
        NSLog(@"Error Response: %@", [s4Response getHttpError]);
        if ([s4Response getRequiresAudit]) {
            NSLog(@"Transaction Requires Audit");
            // Developer needs to add this transaction to a list that requires manual audit
            // See https://docs.shift4.com/guides/response-handling/timeouts-and-communications-failures
        }
    }
}];
```

# Enum Definitions

The enum names are prefixed by S4, to avoid name collisions with other enums you may have.

## S4Mode

S4Mode is used to control the transaction processing mode.

- S4ModeComEng: Commerce engine. Used when processing direct to commerce engine on premises.
- S4ModeComEngCloud: Commerce engine cloud. Used when processing via commerce engine cloud.
- S4ModeHostDirect: 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.

- S4MethodDELETE: http delete
- S4MethodPOST: http post
- S4MethodGET: http get


## S4LogVerbosity

S4LogVerbosity is used to control what messages are written to the optional built-in log file during a transaction. The lower the level of verbosity, the less lines are logged. Error being the lowest level.

- S4LogVerbosityTrace - highest level of logging
- S4LogVerbosityDebug
- S4LogVerbosityInfo - default
- S4LogVerbosityWarning
- S4LogVerbosityError - only errors will show in log


# Class Initializer Definitions

## S4Request

| 
| Initializer Syntax | S4Request |
| Parameters | None |
| Results | S4Request instance |
| Description | S4Request is a class that is used to build and process a request. |


## S4Response

| 
| Initializer Syntax | S4Response |
| Parameters | None |
| Results | S4Response instance |
| Description | S4Response is a class that represents a response. |


# Class Method Definitions

## [S4Request setConfig]

| 
| Method Syntax | - (void)setConfig:(nonnull NSString *)fieldName fieldValue:(nonnull NSString *)fieldValue;
- (void)setConfig:(nonnull NSString *)fieldName mode:(S4Mode)mode;
- (void)setConfig:(nonnull NSString *)fieldName method:(S4Method)method;
- (void)setConfig:(nonnull NSString *)fieldName verbosity:(S4LogVerbosity)verbosity;

 |
| Parameters | - NSString fieldName
  - configuration name
- NSString fieldValue
  - configuration value
- S4Mode mode
  - processing mode
- S4Method method
  - processing method
- S4LogVerbosity verbosity
  - log verbosity / log level

 |
| Results | None |
| Description | Used to set configuration for a request. For a list of configuration values, see [Configuration Options](/sdks/ios#configuration-options) below. This function must be called once for each configuration that is being set. |
| Exceptions | None |


## [S4Request setHeader]

| 
| Method Syntax | (void)setHeader:(nonnull NSString *)fieldName fieldValue:(nonnull NSString *)fieldValue; |
| Parameters | - NSString fieldName
  - header name
- NSString 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:(NSDictionary<NSString *, id> * _Nonnull)request;

 |
| Parameters | - NSDictionary request
  - request argument is the immutable dictionary object that contains the request body structure.

 |
| Results | None |
| Description | This method 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 | (void)process:(void (^_Nonnull)(S4Response * _Nonnull s4Response))completionHandler; |
| Parameters | completionHandler |
| Results | None |
| Description | This async function is used to process a request. This call is **non-blocking**. Calls your completionHandler when the transaction is fully complete, and passes in a new S4Response object automatically. |
| Exceptions | None |


## [S4Response getHttpStatusCode]

| 
| Method Syntax | (NSInteger) getHttpStatusCode; |
| Parameters | None |
| Results | Returns an NSInteger representing the http response code- 200 is a normal/valid response
- anything else is considered an error

 |
| Description | This method 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 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) 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 | (nullable NSDictionary<NSString *, id> *) getResponse; |
| Parameters | None |
| Results | Returns an NSDictionary representing the JSON response. Returns nil in the case of no response. |
| Description | This method is used to obtain an object representing the JSON response. |
| Exceptions | None |


## [S4Response getHeaders]

| 
| Method Syntax | (nonnull NSDictionary<NSString *, NSString *> *) getHeaders; |
| Parameters | None |
| Results | Returns an immutable NSDictionary representing the http response headers |
| Description | This method is used to obtain the http response headers of the transaction. |
| 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:- `S4ModeHostDirect`: this mode is used when you need to send requests directly to the Shift4 host
- `S4ModeComEng`: this mode is used when you need to send requests to commerce engine on premise
- `S4ModeComEngCloud`: 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 http method for the transaction request that you are performing- `S4MethodGET`: process the request using http GET
- `S4MethodPOST`: process the request using http POST
- `S4MethodDELETE`: 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 `S4MethodPOST`

 |


## 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. It’s recommended to keep LogVerbosity at the default level.Logging from the SDK is done at these levels.- `S4LogVerbosityTrace`
- `S4LogVerbosityDebug`
- `S4LogVerbosityInfo`
- `S4LogVerbosityWarning`
- `S4LogVerbosityError`

 |


## 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 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/Apple framework 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.

The [s4Request process] call is non-blocking. Make sure you attach a callback function argument to handle the response.

## Swift Application

S4/Apple is written in Objective C. It is ARC-enabled. You may need to make considerations for this if you’re importing the SDK into a Swift application.

When importing into Swift

- Ensure the `Shift4RestAPISDK.xcframework` is added to the target’s “Frameworks, Libraries, and Embedded Content” with **Embed & Sign**.
- Confirm that the module name `Shift4RestAPISDK` is visible to Swift (`import Shift4RestAPISDK`).
- If you have a mixed Objective‑C/Swift target, ensure your **Objective‑C Bridging Header** and **Swift Compiler** settings are configured correctly so that your own Objective‑C code can interoperate with the SDK types (e.g., `S4Request`, `S4Response`).
- The SDK uses Foundation types (`NSString`, `NSDictionary`, etc.). In Swift you’ll interact with them as bridged types (`String`, `[String: Any]`, etc.) and may need to cast when parsing responses.


## Networking

The SDK uses HTTPS to communicate with the Shift4 REST API. The `Host` configuration must be HTTPS. If you are using any non‑default TLS/ATS behavior, ensure your `Info.plist` configuration still allows connections to the Shift4 endpoints as documented in the [Quick Start](/guides/quickstart).  You will also need to enable outgoing, incoming network capability.