Depending on the platform used, the TIM API module can communicate with the Terminal over different communication channels.

There are various guides covering different use case scenarios. The guide retail is the basic guide and is activated as default. With set_guides the guides can be configured. Important: the configuration needs to include all desired guides (including the retail guide).

Code-example for creating a terminal including settings with activated guides retail and hospitality:

ta_object_t terminal = ta_object_invalid;
ta_object_t settings = ta_object_invalid;

// create terminal settings instance
ta_terminal_settings_create(&settings);

// add wanted guides (with bitwise or)
ta_terminal_settings_set_guides(settings, ta_c_guide_retail | ta_c_guide_dialog);

// create terminal
ta_terminal_create(&terminal, settings);

// release terminal settings
ta_object_release(settings);

//...

// in the end release terminal as well
ta_oject_release(terminal);

The TIM API offers the possibility to perform a Manual Pan Key Entry (MPKE) on ECR side, e.g. if no physical card is present. This can be done by setting the card_ref field in the transaction_datacontainer present in the terminal instance.

This card_ref field must have the following format to reference a non-PCI PAN:

Example: "061234567801234567" : "06" is the prefix that defines the content type that follows (non-PCI PAN), "1234568701234567" is then the non-PCI PAN.

Important: The MPKE on the ECR is only allowed for non-PCI brands, otherwise the manual entry must only be performed on the PIN Pad.

The TIM API C is based on an object-type concept. Most TIM API functions will either take or return parameters in shape of the "opaque type" ta_object_t. For example: ta_terminal_create will create a new terminal-instance, which returns a ta_object_t. On the other hand terminal-function calls like ta_terminal_get_terminal_id require the terminal-instance as parameter of type ta_object_t.

Note: This concept introduces a behaviour similar to certain aspects of object-oriented programming to the environment of C. Similarities are as follows:

• For each object-type there are functions similar to getters and setters, in order to access the object-properties.
  • The naming of getters and setters is as follows: ta_DATATYPE_get/set_PROPERTY
  • e.g.: ta_terminal_settings_get_terminal_id()
• For each object-type there are functions similar to methods, performing object-specific tasks.
  • e.g.: ta_terminal_login()
• For certain object-types create-functions exist, which are similar to constructors.
  • e.g.: ta_string_create()

The memory needed for each object will be allocated and freed by the TIM API itself. However, the user is responsible to release retained objects, when no longer needed. Retained objects are:

• Objects returned by the TIM API as retained objects (e.g. terminal-instance created with ta_terminal_create, or a hardware_information_response-instance returned by ta_terminal_hardware_information).
• Objects that the user explicitly retained by calling ta_object_retain. Basically each ta_object_retain must be paired with a ta_object_release. The TIM API tells you if returned objects are already retained or not. An object that hasn't been retained, must not be released (would lead to errors)! Objects that are returned as not-retained are to read immediately or to explictely retain with ta_object_retain.

(see header-documentation or this doxygen-dok to determine, if objects are retained / not retained. Most IDE support doxygen of header-documentation and will show these information while coding).

/* --- Create list -------------------------------------------------- */
ta_object_t myList = ta_object_invalid;
ta_list_create(&myList);

/* --- Add an integer ----------------------------------------------- */
// Create an object of type integer, since list can only contain
// ta_object_t-instances
ta_object_t myInteger = ta_object_invalid;
ta_integer_create(&myInteger, 1234);
ta_list_add(myList, myInteger);

// Important: User must release the integer-object. Either now or later.
ta_object_release(myInteger);

/* --- Get size of list --------------------------------------------- */
size_t myListSize;
ta_list_get_count(myList, &myListSize);

/* --- Receive first element of list -------------------------------- */
ta_object_t myListElement = ta_object_invalid;
ta_list_get_at(myList, 0, &myListElement);

// do something with element...
// - user is responsible to know how to read /
//   process retreived objects from list
// - in our case here it`s an integer-object
int64_t myIntValue = 0;
ta_integer_get_value(myListElement, &myIntValue);
printf("MyIntValue: %Id\n", myIntValue);

// Important:
// - The list returns list elements as not retained!
// - List element must not be released!

/* --- Release list ------------------------------------------------- */
ta_object_release(myList);

// - At this point, myListElement is no longer (reliably) accessible.
//   Since list has been released, all its elements have been released
//   as well, if no one else is retaining the list elements.

// - If user still wants to use myListElement, he needs to call
//   ta_object_retain(myListElement) right after receiving it from
//   the list. In this case, he later needs to release the list
//   element with ta_object_release(myListElement).

C doesn't provide data types / collections like string, boolean, list, timedate etc. Therefore the TIM API uses and provides a set of basic data types. In various places the TIM API requires or returns these data types.