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

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

• Terminal IP: The IP of the terminal that shall be used afterwards. Used if direct connection is used: ConnectionMode = OnFixIp
• 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 setup with the fixed ip connection mode:

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

The TimApi.cfg file has to be placed in one of two possible locations:

• In the working directory used when the application process is launched. Make sure to set the working directory accordingly for running your application to make sure the TimApi.cfg is found.
• In the same directory as TimApi.dll is located.

The first found TimApi.cfg is used.

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 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 in the corresponding callback method.
• 3. Send commit (if AutoCommit deactivated): After receiving the feedback in the transactionCompleted callback the integrator has to call the 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 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:

// Register listeners on all events that you want to be noticed about.
// You can use multiple event handlers to handle individual events differently if required.
// Handlers can be added and removed any time.
terminal.TerminalStatusChanged += new Terminal.TerminalStatusChangedHandler(onTerminalStatusChanged);
terminal.TransactionCompleted += new Terminal.TransactionCompletedEventHandler(onTransactionCompleted);

.
.
.

void onTerminalStatusChanged(object sender, TerminalStatus trmStatus)
{
    // process terminal status (e.g. CardReaderState)
}

void onTransactionCompleted(object sender, Terminal.TransactionCompletedEventArgs transactionCompletedEventArgs)
{
    // process transaction response
}

Check transaction outcome

To check if a transaction has been performed successfully you have to check the ResultCodewhich is part of the object in theTransactionCompleted callback.

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

---

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: