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.

Specifying referencedTransactionId returns a history of operations performed on that transaction. Most notably, these can include a record of captured transactions, where referencedTransactionId is the transactionId of an authorization transaction. For example, these are the following transaction types that can occur in this history record of a referenced transaction (under the transactionType field): "PRE-AUTH" | "OFFLINE AUTHORIZATION" | "AUTHORIZATION" | "REFUND" | "CAPTURE" | "CANCELLATION" | "TECHNICAL CANCELLATION" | "REVERSAL" | "AUTHORIZATION+TIP" | "TIP".

For example,

{
  "pagination": { "page": 0, "size": 25},
  "referencedTransactionId": "20240822205621368000",
  "terminalId": {terminalId}
}

In the request body above, terminalId is optional but it helps query the transactions processed under a specific terminal id.

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}",
      "transactionDate":" {transactionDate}",
      "amount": {transactionAmount},
      "currency":"EUR",
      "originalTransactionId": "{originalTransactionId}",
      "paymentReason": "Immediate cancellation",
      "receiptNumber": "{receiptNumber}",
      "terminalId": "{terminalId}"
    }`
}

Make sure the terminalId always matches the one where you processed the transaction. Otherwise, you will get "Transaction not found".

For the full JSON schema, refer to Swagger Docs.

Body parameters:

messageType (string) (required) - refer to Table Of Transaction Types.
transactionId (string) (required) is usually put together with transactionDate and a random three digit number e.g. "20240502170" + "021".
transactionDate (string) (required) is in this format: yyyymmddhhmmss. Everything is padded by leading zeros if necessary.
originalTransactionId (string) (required) - the id of the transaction to cancel. For Transaction Payment, this goes under the transactionId field.

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.

PHP SDK

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);
?>

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. With the transactionType of PRE-AUTH, transactions performed with this endpoint are pending to be completed/captured in the step below. For the distinction between PRE-AUTH and AUTHORIZATION, refer to Table of Transaction Types.

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 (string) (required) - "PRE-AUTH" | "AUTHORIZATION"
ecData (string): This property is required in the production environment for processing recurring payments. It specifies the nature of the transaction and helps identify it accordingly. In the testing environment, this value is ignored. The enumerations for this parameter are as follows:
- "INST;": Used for either installment or initial payments in a series, marking it as a Credential On File (COF) initial transaction. This value is only applied in the Request URL. For more details, refer to the Recurring Transaction Request URL.
- "RECU;": Indicates a recurring payment, used for COF MIT (Merchant Initiated Transaction) or Unscheduled Credential On File (UCOF) transactions.
- "CIT;": Denotes customer-initiated transactions that are part of a recurring payment series.

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. In other words, this request captures a PRE-AUTH transaction.

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.

originalTransactionId (string) (required) - the id of the transaction to refund.