PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

Cloud-iA Semi-Integrated Mode

Suggest Edits

This mode is enabled by Bluefin TECS. If you wish to use this mode, please contact TECS support.

The cloud-iA (cloud-integrated API) / semi-integrated mode of TECS SmartPOS adds a TECS client with a REST API to the semi-integrated setup described above. It is suitable for medium to large retail settings. Cloud-iA mode has the advantage of being connectable from any location and gives you the luxury of not having to use the Smart POS SDK, as NaTALI and the REST API handle the entire flow. The REST API receives transactions from the external ECR via HTTP. Cloud-iA mode supports connection to the TECS app store, can handle an extensive range of message types and reduces the potential complexities of a local network configuration.

Cloud-iA Semi-Integrated Mode Integration Workflow

Cloud-iA Semi-Integrated Mode Integration Workflow

Advantages

  • Quick integration.
  • Reduces the potential complexities of a local network setup.
  • The software that is integrated by an ISV is completely managed and overseen by the ISV's own integration team. They are responsible for all aspects of the integration process, thus ensuring that the software works correctly with other systems or platforms.
  • The ERC app issues a HTTP request to the TECS client ECR REST API. The card reader screen prompts the customer to swipe, tap or insert their card. Next, NaTALI sends the transaction to the TECS payment backend systems for processing. Lastly, the response is returned to the ECR app that sent the initial REST API request.

Supported Transactions

  • Sale
  • Sale and tip
  • Refund
  • Refund (referenced)
  • Cancellation (referenced)
  • Preauthorization
  • Completion (capture)

Supported Message Types

  • Sale or preauthorization = 0001
  • Sale and tip = 0907
  • Refund = 0011
  • Cancellation or capture = 0013

Supported Features

  • TECS app store.
  • Connect from anywhere using the REST API, which provides flexibility and ease of access.

Common Concerns

  • Connection reliability: because network stability is crucial, our solution includes safeguards to automatically handle lost connections, thus preventing incomplete or erroneous transactions from being made and ensuring operational reliability and accuracy. If a connection is lost, the ISV software cancels the transaction. This prevents a scenario where the acquirer accepts a transaction, the TECS engine forwards the response to the TECS client via the REST API, but there is no connection between the REST API and the ECR. The REST API does not have a mechanism to handle this scenario. In short, any time the ECR does not receive a response, the transaction has to be cancelled.
  • Interconnection stability: the design ensures robust interaction between the TECS client and TECSxml, thus enhancing reliability even in complex infrastructures.

Possible Uses

Cloud-iA (cloud-integrated API) / semi-integrated mode works in scenarios with one or more ISV systems controlling at least one POS terminal with access to NaTALI via a REST API.

API Reference

In this mode, the device is primed to receive the REST API call from the ECR. As explained above, once the REST API call is initiated, the device switches to the card reader screen mode, prompting the customer to swipe, tap or insert their card. The response from the REST API is then sent back to the ECR.

📘

Also see

Sale Transaction

After this transaction request is made, the customer is prompted to swipe, tap or insert their card (given that the card_number is omitted compared to Moto Transaction). This is a CIT transaction.

Request Configuration

POST https://{-*}.tecs.at/tecsclientrest/makeTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "amount": "{Amount}",
      "authorization_number": "",
      "card_number": "",
      "currency": "EUR",
      "cvc2": "",
      "desired_currency": "EUR",
      "ecr_data": "",
      "language": "EN",
      "message_type": "0001",
      "password": "",
      "payment_reason": "Test Sale",
      "payment_reasonAsByte": "",
      "personal_id": "",
      "receipt_layout": "01",
      "receipt_number": "1",
      "terminal_number": "{terminalId}",
      "transaction_date_time": "{transactionDate}",
      "transaction_id": "{transactionId}",
      "transaction_origin_identifier": "1",
      "transaction_origin_indicator": "0",
      "transaction_place": "BA",
      "transaction_source_id": "1"
    }`
}

Moto Transaction

Request Configuration

In contrast to the previous example, you need to change transaction_origin_indicator to 2, thus specifying the MOTO type of transaction for recurring payments. The card_reference needs to be specified so that the customer doesn't have to input/read their card to proceed with the transaction. Essentially, this is a sale transaction.

For more, see References and Table Of Transaction Types.

POST https://{-*}.tecs.at/tecsclientrest/makeTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "amount": "{Amount}",
      "authorization_number": "",
      "card_number": "{card_reference}",
      "currency": "EUR",
      "cvc2": "",
      "desired_currency": "EUR",
      "ecr_data": "",
      "language": "EN",
      "message_type": "0001",
      "password": "",
      "payment_reason": "Test Moto",
      "payment_reasonAsByte": "",
      "personal_id": "",
      "receipt_layout": "01",
      "receipt_number": "1",
      "terminal_number": "{terminalId}",
      "transaction_date_time": "{transactionDate}",
      "transaction_id": "{transactionId}",
      "transaction_origin_identifier": "2",
      "transaction_origin_indicator": "2",
      "transaction_place": "BA",
      "transaction_source_id": "1"
    }`
}

Cancel Transaction

To cancel a transaction, you use the same API endpoint with a different message type: "0013" and card_number. This represents the original transaction identifier padded with zeros in order to increase the length to 20, and has the prefix "TXID".

Request Configuration

POST https://{-*}.tecs.at/tecsclientrest/makeTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "amount": "{Amount}",
      "authorization_number": "",
      "card_number": "TXID00020240521190912161",
      "currency": "EUR",
      "cvc2": "",
      "desired_currency": "EUR",
      "ecr_data": "",
      "language": "EN",
      "message_type": "0013",
      "password": "",
      "payment_reason": "Test Moto",
      "payment_reasonAsByte": "",
      "personal_id": "",
      "receipt_layout": "01",
      "receipt_number": "1",
      "terminal_number": "{terminalId}",
      "transaction_date_time": "{transactionDate}",
      "transaction_id": "{transactionId}",
      "transaction_origin_identifier": "2",
      "transaction_origin_indicator": "2",
      "transaction_place": "BA",
      "transaction_source_id": "1"
    }`
}

Referenced Refund

A referenced refund is processed via /makeTransaction where the card_number parameter is composed of transaction and terminal identifier in the following format.

`TXID${padWithZeros(transactionId)}_01_${terminal_ID}`

We used JavaScript for this code snippet.

🚧

Note

The transaction identifier is padded with zeros to satisfy the length of transactionId to be 20.

The prefix TXID represents the original transaction id to refund.

Request Configuration

POST https://{-*}.tecs.at/tecsclientrest/makeTransaction

{
  "amount": "101",
  "authorization_number": "",
  "card_number": "TXID00000000000001451003_01_11460019",
  "currency": "USD",
  "cvc2": "",
  "desired_currency": "USD",
  "language": "en",
  "message_type": "0011",
  "password": "",
  "payment_reason": "Test refund",
  "payment_reasonAsByte": "",
  "personal_id": "",
  "receipt_layout": "01",
  "receipt_number": "1",
  "terminal_number": "11460019",
  "transaction_date_time": "20241127093846",
  "transaction_id": "1451004",
  "transaction_origin_identifier": "2",
  "transaction_origin_indicator": "2",
  "transaction_place": "60606",
  "transaction_source_id": "1"
}

For a typical refund, see API Examples Transaction Refund.

Updated 24 days ago