API Examples

JSON Web Service

Transaction data can be handled on either the client-side or the server-side. In this example, we handle all data on the client side (browser). However, the client (shop) has the flexibility to choose which aspects of the transaction data it wants to handle on the client-side versus the server-side.

Server Side

<?php
require '/path-to/tecsweb-php-lib/loader.php'; // composer: require 'vendor/autoload.php';

// Data provided by client (browser)
$data = json_decode(file_get_contents('php://input'), true);

/************************************/
/** Place for preparing transaction */
/************************************/
// header("Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'");

$tecs = new \Tecs\TecsWeb(
    'SecretKey', // Private secret key provided by TECS
    'MerchantId', // Merchant ID provided by TECS
    'https://test.tecs.at/tecsweb/tecswebmvc_start.do' // URL of payment portal
);
try {
    $url = $tecs->createSignedUrl([
        \Tecs\TecsWeb::AMOUNT         => $data[\Tecs\TecsWeb::AMOUNT],
        \Tecs\TecsWeb::TX_ID          => $data[\Tecs\TecsWeb::TX_ID],
        \Tecs\TecsWeb::TX_CURRENCY    => $data[\Tecs\TecsWeb::TX_CURRENCY],
        \Tecs\TecsWeb::TX_DESC        => $data[\Tecs\TecsWeb::TX_DESC],
        \Tecs\TecsWeb::RECEIPT_NUMBER => $data[\Tecs\TecsWeb::RECEIPT_NUMBER],
        \Tecs\TecsWeb::RETURN_URL     => $data[\Tecs\TecsWeb::RETURN_URL],
        \Tecs\TecsWeb::TX_DATE_TIME   => $data[\Tecs\TecsWeb::TX_DATE_TIME]
    ]);
    // Create successful JSON response
    header("Content-Type: application/json");
    // header("Content-Security-Policy: frame-ancestors 'none'");
    exit(json_encode([
        'tecsWebRequestToken' => $url->getSignedUrl()
    ]));
} catch (\Exception $e) {
    // Create JSON response on error
    header("Content-Type: application/json");
    exit(json_encode([
        'error' => $e->getMessage()
    ]));
}

?>

Client Side

<html>
  <head>
    <script src="https://test.tecs.at/tecsweb/js/tecsweb.js"></script>
  </head>
  <body>
    <div id="tecsweb-payment-wrapper"></div>
    <script>
        const padZero = (num) => {
          return String(num).padStart(2, '0');
        }

        const makeTransactionDateTime = () => {
          const currentDate = new Date();

          const year = currentDate.getFullYear();
          const month = padZero(currentDate.getMonth() + 1);
          const day = padZero(currentDate.getDate());
          const hours = padZero(currentDate.getHours());
          const minutes = padZero(currentDate.getMinutes());
          const seconds = padZero(currentDate.getSeconds());

          const formattedDate = `${year}${month}${day}${hours}${minutes}${seconds}`;
          return formattedDate;
        }

        const data = {
          [TecsWeb.AMOUNT]: '100',
          [TecsWeb.TX_ID]: '1000017864914',
          [TecsWeb.TX_CURRENCY]: 'EUR',
          [TecsWeb.TX_DESC]: 'Test TecsWeb',
          [TecsWeb.RECEIPT_NUMBER]: '123456',
          [TecsWeb.RETURN_URL]: 'https://tecsweb-iframe-test.loc/payment-response.php',
          [TecsWeb.BACKEND_SIGN_URL]: 'https://tecsweb-iframe-test.loc/get-tecsweb-token.php',
          [TecsWeb.TX_DATE_TIME]: makeTransactionDateTime()
        };

        TecsWeb.getSignedUrl(data).then(function (response) {
          // create a button or an iframe with response.data.tecsWebRequestToken
        });
              
    </script>
  </body>
</html>

BACKEND_SIGN_URL is the endpoint of the JSON web service, which, in successful cases, returns TecsWebRequestToken.

TecsWeb.getSignedUrl(data)

  • This function is especially useful in fetching the tecsWebRequestToken from the server side that is written in a language that the TECS Web SDK does not support such as C++, Rust, Python, etc. In the Example Use Cases, we set up a NodeJS server walking you through this scenario.

Transaction History

It is best to run a pagination query before performing a transaction cancellation or similar transaction operation. This is because the pagination query delivers some of the body parameters required for the cancellation request payload, such as originalTransactionId, transactionAmount, transactionCurrency, receiptNumber, terminalId, and clientId.

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/transactionHistory

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "pagination": { "page":0, "size":15 },
      "transactionDateFrom":"2024-05-01T00:00:00.000",
      "transactionDateTo":"2024-05-24T23:59:59.999"
    }`
}

For the full JSON schema, refer to Swagger Docs.

This request returns all the transactions made between transactionDateFrom and transactionDateTo with pagination.

Transaction Cancellation

For transaction cancellation, we use the Merchant Services REST API.

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/cancelTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "messageType": "0013",
      "clientId": 1,
      "transactionId": "{transactionId}",
      "transactionOrigin": 2,
      "transactionDate":" {transactionDate}",
      "amount": {transactionAmount},
      "currency":"EUR",
      "originalTransactionId": "{originalTransactionId}",
      "paymentReason": "Immediate cancellation",
      "receiptNumber": "{receiptNumber}",
      "terminalId": "{terminalId}"
    }`
}

For the full JSON schema, refer to Swagger Docs.

Body parameters:

  • messageType (required) - refer to Table Of Transaction Types.

  • transactionId (required) is usually put together with transactionDate and a random three digit number e.g. "20240502170" + "021".

  • transactionDate (required) is in this format: yyyymmddhhmmss. Everything is padded by leading zeros if necessary.

  • transactionOrigin (optional)

TECS Transaction Status

The merchant services REST API is usually used to get a transaction status.

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/statusTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "sourceId": 1,
      "transactionId": "{transactionId}",
      "terminalId": "{terminalId}"
    }`
}

For the full JSON schema, refer to Swagger Docs.

The PHP SDK also supports class TecsWebTransactionStatus to get the transaction status on the server side. Essentially, this is a REST API wrapper set up with the php-curl utility and curl_init. In other words, it is straightforward to set up REST API calls that the PHP SDK doesn't support on the server side.

<?php
  require 'vendor/autoload.php';

  $tecs_web_transaction_status = new \Tecs\TecsWebTransactionStatus(
    'merchantId', // terminal ID
    'secretKey',
     'test',
  );

  $transaction_status = $tecs_web_transaction_status->getTransactionStatus('originalTransactionId');

  print_r($transaction_status);
?>

Body parameters:

  • originalTransactionId (required)

Transaction Payment

Bluefin TECS also uses the merchant services REST API to support the processing of transaction payments. This is particularly useful for recurring payments, as pointed out in the Use Cases.

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/paymentTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "cardNumberReference": "{cardNumberReference}",
      "transactionType": "{transactionType}",
      "transactionId": "{transactionId}",
      "transactionDate": "{transactionDate}",
      "terminalId": {terminalId},
      "clientId": 1,
      "cvc": "",
      "amount": {transactionAmount},
      "currency": "EUR",
      "receiptNumber": "{receiptNumber}",
      "paymentReason": "test sale",
      "terminalLocation": "BA",
      "password": "{terminalPassword}",
      "ecData": "",
      "ecrData": "",
      "emvData": "",
      "languageCode": "EN",
      "receiptLayout": 99
    }`
}

For the full JSON schema, refer to Swagger Docs.

Body parameters:

  • transactionType (required) - "PRE-AUTH" | "OFFLINE AUTHORIZATION" | "AUTHORIZATION" | "REFUND" | "CAPTURE" | "CANCELLATION" | "TECHNICAL CANCELLATION" | "REVERSAL" | "AUTHORIZATION+TIP" | "TIP"

Pre-Authorization Completion

Payments (sale or PRE-AUTH) are processed by calling the REST API. This sends the payment to the acquirer for authorization and returns the response to the webshop, where the application flow is completed.

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/preAuthCompletionTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "transactionId": "{transactionId}",
      "transactionDate": "{transactionDate}",
      "terminalId": {terminalId},
      "clientId": 1,
      "amount": {transactionAmount},
      "currency": "EUR",
      "receiptNumber": "{receiptNumber}",
      "paymentReason": "test completion",
      "originalTransactionId": "{originalTransactionId}"
    }`
}

For the full JSON schema, refer to Swagger Docs.

Transaction Refund

Request Configuration

POST https://{-*}.tecs.at/merchantservices/public/refundTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "messageType": "0011",
      "transactionId": "{transactionId}",
      "transactionDate": "{transactionDate}",
      "terminalId": {terminalId},
      "clientId": 1,
      "amount": {transactionAmount},
      "currency": "EUR",
      "receiptNumber": "{receiptNumber}",
      "paymentReason": "Order Errors",
      "originalTransactionId": "{originalTransactionId}"
    }`
}

For the full JSON schema, refer to Swagger Docs.


What’s Next