The TIM API is the standard application interface for ECR integration using SIX Payment Services terminals.

TIM API provides a comprehensive feature set to support the requirements of several different markets. This guideline is intended to be used by ECR integrators that need to implement the TIM API functionality in their products.

The following document contains an overview structure, description of the TIM API modes synchronous/asynchronous and describes the corresponding functions, notifiers and data elements that can be used with the TIM API. Furthermore implementation examples are provided. Nevertheless always the corresponding description of a function or data element is authoritative, not the examples.

For further information about the architecture of the TIM API can be found in [B1], this document is meant to cover only implementation purposes.

The configuration of the terminal can be done by creating and configuring a terminal_settings-instance. The terminal_settings-instance must then be passed to the terminal_createfunction.

Once a terminal-instance has been created with a terminal_settings-instance, the settings can not be changed anymore. Changes to the terminal_settings-instance will be ignored.

The network and guides configuration are explained in the following chapters. For further information refer toterminal_settings.

Follow these basic steps for using the TIM API:

1. Create terminal_settings and initialize connection parameters (see Setup Configuration)
2. Create terminal instance using the created terminal_settings
3. Set some properties if needed:
   • set pos_id
   • create mandatory list of ecr_info and add with ta_terminal_add_ecr_data
   • create list of print_options and set with set_print_options
   • add listeners (ta_terminal_add_listeners)
4. connect and login. This can be done automatically, when the first terminal operation is called or manually using the login method.
5. Use terminal operation functions.

A basic flow to show a dialog is:

The TIM API uses two different types of automatisms:

• Pre-Automatisms: This means that all actions that need to be done before a function can be called. E.g. a transaction can be called in disconnected state without having called connect, login and activate in advance. These are called automatically by the TIM API before the transaction is performed. The Pre-Automatisms are enabled by default.

• Post-Automatisms: These automatisms can be enabled or disabled using the members auto_commit and fetch_brands. A Post-Automatism is triggered after an action has been performed. E.g. if a connect has been called and fetch_brands is activated, an application_information request is called automatically after the connect. Or if auto_commit is activated a commit is performed automatically after a transaction has been made. auto_commit and fetch_brands are enabled by default.

The following diagrams show the principle of the Pre-Automatisms and Post-Automatisms. Pre-Automatisms are enabled by default and cannot be disabled. If an error occurs the started request from the ECR is returned with an error.

Synchronous flow

Asynchronous flow

The basic operation modes of terminal function calls are:

1. Synchronous
   Function calls are blocking and return after the operation has finished. Error code is provided and indicates if request was successful or not.

2. Asynchronous
   Function call returns immediately after the operation has started successfully. A user-implemented callback function will then be called, after operation has finished. All callback functions receive an event. The event contains a result_code indicating if there were errors or not. The user-implemented callback function has to be registered with add_listener.

Functions called on terminal perform synchronous by default. The asynchronous method has the same name with _aync appended to its name.

Code example for adding a terminal listener:

/*
 * Example for adding a terminal status listener
 *
 * \param[in] terminal Terminal instance
 */
void add_status_listener(ta_object_t terminal) {
    ta_object_t listener = ta_object_invalid;
    ta_s_terminal_listener_t listener_config;

    // clear listener-config
    memset(&listener_config, 0, sizeof(listener_config));

    // add user-implemented callback to listener-config
    listener_config.terminal_status_changed = mylistener_terminal_status_changed;

    // optional: add user content to listener,
    // pointer will be handed over to all callbacks:
    //listener_config.user_pointer = &custom_struct;

    // create listener-object
    ta_terminal_listener_create(&listener, &listener_config);

    // add listener-object to terminal
    ta_terminal_add_listener(terminal, listener);

    // release listener-object
    ta_object_release(listener);
}

/*
 * Callback for terminal status changes
 *
 * Will be called when status of terminal changes.
 * \param[in] terminal Terminal instance
 * \param[in] user_pointe User-pointer which can be set in the terminal listener
 */
void mylistener_terminal_status_changed(ta_object_t terminal,	void *user_pointer) {

	// implement your code to process status change here...
	//printf(" > listener_terminal_status_changed\n");
}