The following sections give a simple overview how to make a simple TIM API integration without any special configurations. Therefore default values are used as often as possible to keep it simple. If special features are required, visit the section Integration in Detail for a more sophisticated overview.

As the TIM SDK offers the TIM API in multiple languages you can chose the one that is suitable for your platform. To use the TIM API Swift you have to import the Framework-Archive into your project in the programming environment you are using. The file include path may have to be adjusted accordingly, depending where you place the TIM API.

To start right away only a minimal set of settings has to be given:

• Terminal ID: The ID of the terminal that shall be used afterwards. Used for broadcast connection (Default).
• Terminal IP: The IP of the terminal that shall be used afterwards. Used if direct connection is used: ConnectionMode = OnFixIp
• ConnectionMode: Only if "OnFixIp" with set Terminal IP shall be used. (Default: ConnectionMode = Broadcast)
• AutoCommit: Defines if terminal performs a Commit automatically or if it must be done from the ECR. (Default: AutoCommit = true)

This minimal configuration can be done directly in the code after creating aTerminalSettings instance.

This block shows the minimal setup with broadcast connection mode:

This block shows the setup with the fixed ip connection mode:

After the Terminal instance has been created it can be used to perform transactions.

The flow on the right shows a simple transaction flow and which steps are done by which participant. Note that for a simple use the integrator only needs to follow 4 simple steps, steps 1 to 4. Steps 1-4 can be performed multiple times (loop) if wished. The rest, steps A to G, will be done either by the TIM API itself or by the terminal if required.

The steps the integrator has to perform are the following:

• 1. Start transaction: The integrator has to call the transactionAsync function including the required parameters which are shown in the code example below.
• 2. Process transaction completed: After processing the transaction the TIM API will return a transactionResponsein the corresponding transactionCompleted callback method.
• 3. Send commit (if AutoCommit deactivated): After receiving the feedback in the transactionCompleted callback the integrator has to call the commitAsync function to complete the transaction process. This step must only be done if AutoCommit has been set to "false" in the terminal settings.
• 4. Process commit completed (if AutoCommit deactivated): Also the commit function is finished from the TIM API by calling the commitCompleted callback function. After getting the commit completed callback call from the TIM API, another requests, e.g. another transaction, can be called.

The following steps are performed by the TIM API or the terminal if they are required:

• A. : The TIM API automatically connects to the terminal and makes the required Login to set the specified connection parameters. If successful a shift will be opened on the terminal by calling Activate from the TIM API automatically. These steps are only performed if they are required which means the terminal was not yet in the corresponding state and not yet ready to accept a transaction:
  • If the terminal is already connected, no connect is required.
  • If the terminal is already in LoggedIn state, no login is required.
  • If the terminal is already in Activated state (open shift), no activate is required.
• B. : After the TIM API performed all steps needed to bring the terminal into the required state, the transaction request is sent to the terminal.
• C. : The terminal performs the transaction (e.g. cardholder verification, transaction authorization etc.)
• D. : The terminal returns the outcome of the transaction to the TIM API.
• E. : The TIM API sends the commit request to the terminal (will be done automatically, if AutoCommit is activated).
• F. : The terminal processes the commit request.
• G. : The terminal sends the commit response to the TIM API.

In code this may look as follows:

The following section explains how to easily retrieve response data from the which is available after a transaction as described above.

The first step is to implement your own terminal listener class wherein you overwrite the functions you want to use. If you are mainly interested in the transaction response you can use the following code:

//
// Handle asynchronous terminal events.
//
class TerminalHandler: DefaultTerminalListener {

    //
    // The status of the terminal changed. This includes processing status and display content
    //
    override func terminalStatusChanged(terminal: Terminal) {
        // Events usually originate from a different thread than the main thread.
        // Always use DispatchQueue.main.async to be safe
        DispatchQueue.main.async {
            // handle terminal status change
        }
    }

    //
    // A call to Terminal.transactionAsync finished.
    //
    override func transactionCompleted(event: TimEvent, data: TransactionResponse?) {
        // Events usually originate from a different thread than the main thread.
        // Always use DispatchQueue.main.async to be safe
        DispatchQueue.main.async {
            // handle transaction finished using data
        }
    }
}

class ExampleECR {    
    func createTerminal(settings: terminalSettings) {
        // create terminal from terminal settings
        guard let terminal = Terminal(settings: terminalSettings) else {
            // throw error, since creating terminal from settings failed
            return
        }

        // add listener (can be done at sany time, not just during init)
        terminal.addListener(listener: TerminalHandler())
    }
}

Check transaction outcome

To check if a transaction has been performed successfully you have to check the ResultCode which is part of the TimEvent object in thetransactionCompleted callback.

Further error information can be retrieved as described in the API documentation in the TimException section.

IMPORTANT: Please note that only the enum value of the ResultCode can be used and NOT the int value, as this is generated code and the int value may not correspond to the int value shown in the TIM API log.

---

Print data

The TransactionResponse has a member PrintData (accessed via getPrintData) which contains merchant and cardholder receipts.

The PrintData returned in the TransactionResponse contains a merchant and a cardholder receipt which can be retrieved in the transactionCompleted callback using the getPrintData function. The PrintData object then contains a list of Receipt objects which can be retrieved individually.

---

Card data

To retrieve card specific information the CardData object is also available in the TransactionResponse. This object contains several card information that was available to the terminal during the transaction process.

---

Further transaction information

Further information regarding the transaction can be found in the TransactionInformation object.

The following code shows how the information mentioned above can be retrieved in the transactionCompleted event: