Overview

This document outlines the integration process and API details for the Bluefin TECS Web eCommerce system, which is used for processing card transactions through a merchant's online shop.

TecsWeb JS

Integrating an iframe can present some challenges.

One issue is resizing the iframe to match the dimensions of the child page content as users navigate through different pages within the iframe.

Another challenge is ensuring communication between the child and parent pages. When a return URL is defined, TecsWeb will redirect to this URL after the payment is completed. However, since this URL opens within the iframe, you need a way to inform the parent page about the transaction status and details.

Default Appearance

Customized Appearance

TecsWeb.createIframe(
  'tecsweb-iframe-customized',
  response.data.tecsWebRequestToken,
  {
    backgroundColor: '#eee',
    scrollBar: true,
    iframeSize: 'small', // (small | medium | large), medium is default
    width: '600px', // if defined, overrides predefined iframeSize
    height: '1000px' // if defined, overrides predefined iframeSize
  }
);

For response.data.tecsWebRequestToken in use, check out JSON Web Service Example.

Button Styling

// Button Styling
{
  label: `Order for 1 \u20AC`,
  style: {
    backgroundColor: '#066fc9',
    color: '#FFF',
    borderRadius: '6px',
    border: '2px solid #066fc9',
    cursor: 'pointer',
    fontSize: '16px',
    padding: '8px 16px',
    fontWeight: 'bold'
  },
  styleHover: {
    backgroundColor: '#0680dd'
  },
  styleDisabled: {
    backgroundColor: 'rgb(115,141,201)',
    color: '#d6d4ff',
    border: '2px solid #066fc9',
  },
  scrollBar: false,
  iframeSize: 'medium', // small,  medium, large (medium is default)
  hideOnOpen: false,
  onPopupClose: () => confirm('Your callback after close')
}

Iframe Styling

// Iframe Styling
{
  backgroundColor: '#eee',
  scrollBar: true,
  iframeSize: 'small', // (small | medium | large), medium is default
}

Customized Appearance Configuration

• iframeSize (string) (Optional): "small" | "medium" | "large"

  • "small" - width: 500px, height: 1350px
  • "medium" - width: 800px, height: 1400px
  • "large" - width: 1000px, height: 1000px

• width | height (string | number) (Optional):

  • For further customization of the iframe size, these are set in the following format

    • number: 100 - this turns into "100px"

    • string: "100px" | "50%"

    🚧

    Note

    These options overwrite the iframeSize option

Iframe Resizing

Typically, you define the dimensions of an iframe and decide whether it should display a scrollbar if the content overflows its height.

But what if you need to dynamically change the dimensions based on the content of the child page?

To address this, we have integrated iframe-resizer in our TecsWeb library.

For full details about iframe-resizer, please visit: https://iframe-resizer.com.

In brief, you need to load the parent JavaScript into your parent page and the child JavaScript into your child page.

In this scenario, our TecsWeb page acts as the child page, so we've already implemented the child JavaScript on our pages. You only need to implement the parent JavaScript.

For effective communication with TecsWeb, we strongly recommend using iframe-resizer as wrapped in our TecsWeb library. This ensures that both the parent and child pages use the same version of iframe-resizer.

For example, this is how to use our iframe-resizer wrapper.

<script>
  TecsWeb.iframeResize({ license: "xxxx" });
  // For more options, see https://iframe-resizer.com/api/parent
</script>

🚧

Note

The Iframe Resizer is available under a GPLv3 license for non-commercial use only. For use in cross-domain scenarios, there is a fee of $76. For more information, visit https://iframe-resizer.com/pricing

Communication Between Child and Parent Pages

As mentioned earlier, the Return URL provided to TecsWeb will open in the iframe after the payment is processed. Therefore, your parent page needs to be informed about the status of the payment transaction.

In a cross-domain scenario, the only solution for this is to fire the "message" event using the postMessage function supported by JavaScript.

Here is a simple example of the child-parent relationship:

Child Page

window.parent.postMessage("Fired from the child page");

Parent Page

window.addEventListener("message", function (event) {
  if (event.data == "Fired from the child page") {
      // DO SOMETHING
  }
}});

Triggering with postMessage

Without having to code PHP, you can choose this method where you can fire this event from the Return page as follows:

<!DOCTYPE html>
<html>
  <head>
    <script src="https://test.tecs.at/tecs/js/tecsweb.js"></script>
  </head>
  <body>
    <script>
      window.parent.postMessage(TecsWeb.getQueryString())
    </script>
  </body>
</html>

🚧

Note

For this event to get registered, don't forget to add the event listener to the main parent page as noted above.

Another alternative solution would be to move all the data to the parent to the same URL, or to the different one. This solution is put to use using TecsWeb.redirectParent.

redirectParent #1

In this example, the PHP code handles the TecsWeb response - then, the TecsWeb.redirectParent function redirects the parent to the URL passed as the first argument of this function.

<html>
  <head>
    <?php
      // handle the response
      // check the signature
      // collect GET data
      // saving to database or some other operation
      // handle successful or errorous response
    ?>
    <script src="https://test.tecs.at/tecs/js/tecsweb.js"></script>
  </head>
  <body>
    <script>
      TecsWeb.redirectParent("after-trasaction.php?transaction=OK");    
    </script>
  </body>
</html>

redirectParent #2

On the other hand, here we omit the PHP code to jump straight to redirecting the parent to the given URL.

<script>
  const responseDataQueryString = TecsWeb.getQueryString();
  TecsWeb.redirectParent(
    'after-trasaction.php?' + responseDataQueryString
  );
</script>

With getQueryString, we can get all the response query parameters for reuse in the parent page about the status and details of the processed transaction.

PHP SDK REFERENCE

\Tecs\TecsWeb:: means that the given attributes are in that namespace e.g. \Tecs\TecsWeb::AMOUNT.

• class TecsWeb

  • __construct(secretKey, merchantId, paygateUrl)

    • merchantId (string) (Required)

      • Often referred to as terminalId

    • secretKey (string) (Required)

    • paygateUrl (string) (Required)

      • TECS Web Payment Portal

  • createSignedUrl(array)

    • array - transaction configuration e.g. [ \Tecs\TecsWeb::AMOUNT => '100' ].

    • \Tecs\TecsWeb::

      • AMOUNT (string) (Required)

        • Transaction amount in cents.

      • TX_ID (string) (required)

        • transactionId

        🚧

        Note

        This identifier must be unique per transaction.

        We recommend using the Unix Epoch current timestamp format with milliseconds for uniqueness. For example, in Bash we have echo $(date +%s%N | cut -b1-13). In JavaScript, Date.now(). For various other languages, please refer to Current Millis ‐ Milliseconds since Unix Epoch.

        Feel free to use your logic generating a unique ID. For example, a sequence of random integers, or similar.

      • TX_CURRENCY (string) (required)

        • ISO 4217 currency code

      • TX_DESC (string) (required)

        • Transaction description

      • RECEIPT_NUMBER (string) (required)

        • Invoice number - useful for tracking purposes.
        • Receipt number of the request should identify business process on the eshop side.
        • Should be unique per loading procedure.

      • RETURN_URL (string) (required)

        • Target URL that handles the transaction response e.g. validation, status, etc.
        • /vterm/purchase.jsp is provided by Bluefin TECS as the complementary RETURN page, which you can use when you don't want to create your own customized page to process the purchase. The RETURN page is also useful for testing and debugging.

      • TX_DATE_TIME (required) (default: current_date)

        • Transaction date and time (format = yyyymmddhhmmss)

      • TX_SOURCE_ID (integer) (optional) (default: 1)

        • Merchant account ID (for multi-account systems)

      • TX_PLACE (string) (optional) (default: "")

        • Describes the place (e.g. webshop name) where the transaction took place

      • USER_DATA (string) (optional) (default: "")

        • The USER_DATA field is for supplementary information that a shop wants to keep for particular transactions. This encompasses data collected for enhanced cardholder verification, as well as straightforward tags intended for subsequent analysis or statistical insights.

      • LANG (string) (optional) (default: "en")

        • Forces the TECS Web page to be displayed in a certain language. Possible values: en, de, it, es, fr, pl.

      • MESSAGE_TYPE (integer) (optional) (default: 0001)

        • Type of transaction request

      • TX_ORIG_ID (integer) (optional) (default: 2)

        • Additional information for the transaction type as provided in the parameter MESSAGE_TYPE

      • **ORIG_TX_ID (integer) (optional) **

        • Original transaction number (txid of the source transaction)

      • CARD_NUMBER_POST (string) (optional) (default: "")

        • Should be in the format "cardnumber_expirydate" (for more details see the TXML spec). If this parameter is present, the TECS Web page shouldn't ask the cardholder to enter any data.

      • EC_DATA (string) (optional | required)

        • Note that this parameter is only required in the production environment for processing subsequent recurring transactions. See Payment Gateway Endpoints.

        • "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.

• class TecsWebTransactionStatus

  • __construct(merchantId, secretKey, mode = 'prod')

    • merchantId (string) (required)

      • Often referred to as terminalId

    • secretKey (string) (required)

    • mode (string) (optional) 'prod' | 'test'

  • getTransactionStatus(transactionId) -> TransactionStatusResponse

    • transactionId (string) (required)
      • Original transaction identifier from Creation of TECS Web Request Token

• class TecsWebResponse

  • __construct(secretKey, data)
    • secretKey (string) (required)
    • data (array) (required)
      • Return parameters parsed from response URL as an array. These include responsecode, responsetext, txid, etc. This response URL is retrieved by the payment gateway.
  • isSignedCorrectly() -> bool
    • Checks if the response has valid signature
  • getResponseText() -> string
    • Returns responsetext from response URL
  • getResponseCode() -> string
    • Returns responsecode from response URL
  • getTXID() -> string
    • Returns unique transaction ID
  • getTXDateTime() -> string
    • Returns the transaction time stamp
  • getAuthorizationNumber() -> string
    • Returns the authorization number
  • getAcquirerName() -> string
    • Returns the acquirer name
  • getCardReferenceNumber() -> string
    • Returns the card reference number
  • getCardType() -> string
    • Returns the card type
  • getUserData() -> string
    • Returns the user data
  • getSign() -> string
    • Returns the hashed signature
  • getAllData() -> array
    • Returns response URL parameters as an array

Table of Transaction Types

🚧

Note

* - represents the transactions that aren't supported by the eCommerce platform but can be performed with either Merchant Services REST API or TECS SmartPOS.

Request URL Parameters

Required Parameters

Optional Parameters

Response URL Parameters

After the transaction request is successfully processed, the customer is redirected back to the online shop along with the result of the transaction. The customer is redirected back to the URL of the transaction request, which is specified by parameter "rurl". Depending on the response, the shop may notify the customer about the result of the authorization request.

CardReferenceNumber - returned when the ecdata parameter is specified.

• For approved transactions:
  • Format: REFY….Y_ZZZZ_XXXX_AAAAAA
  • REF – string identifier
  • Y….Y – variable length string - card reference number generated by payment engine
  • ZZZZ – 4N – card expiration date (YYMM)
  • XXXX – 4N – last 4 digits of PAN
  • AAAAAA – 6N – first 6 digits of PAN
• For declined transactions, field contains last 4 digits of PAN

Missing Response

Sometimes, the response might not get back to the merchant shop system because of various accidents (customer closes the browser, browser crashes, internet connection failure, etc). In this case, the shop cannot evaluate the response and has to consider the payment as failed.

However, the payment request still might have been authorized and the card holder will be billed by their card issuer without receiving the goods or services they ordered from the merchant.

To avoid this situation, the shop system needs to keep track of all requests and handle them accordingly. There are several ways to handle this situation:

• Automatically send a cancellation request for each transaction request with unknown result.
• Use Bluefin TECS Transaction Web Service to check the status of a transaction and react accordingly.

For more options and best-practice procedures, please reach out to your TECS consultant.

Secure Hash

The secure hash is a sequence of characters that ensures the authenticity of given parameters. It is calculated using a one-way cipher algorithm.

The secure hash consists of the following parameters:

• amt
• txid
• txcur
• txdesc
• mid
• rurl
• User-Data ( optional )

The secure hash is calculated with these parameters and the MerchantSecretKey. All the parameters needed for the hash are delimited by the pipe character '|' in the order specified below. It is critical that the values in the hash are not URL encoded.

As mentioned earlier, the hash algorithm is determined in accordance with the hashed signature length.

Hash Signature Table

Data for signature can be encoded with either US-ASCII or UTF-8 Charset. TECS Web checks for both of them on request validation.

Manual Hash Calculation

Request URL

By default, the PHP SDK uses SHA-256 for hashing the signature. The hashing also can be done manually as shown in the bash example below.

#!/bin/bash
AMT='100'
TransactionId='1000010165' # Optimally, consider using the current Unix Epoch timestamp for uniqueness: $(date +%s%N | cut -b1-13)
txCur='EUR'
txDesc='Transaction Description'
MerchantId='MerchantId'
RURL='http://127.0.0.1:8000/payment-response'
userData='CHI=1108;'
skey='SecretKey'
sigData="$AMT|$TransactionId|$txCur|$txDesc|$MerchantId|$RURL|$userData$skey"
signature=`echo -n "$sigData" | openssl dgst -sha256 -binary | xxd -p`
S=`echo -n $signature | awk '{print toupper($0)}'`
echo "$S"

It is important to note that the secretKey is appended, NOT separated by a delimiter. For example, if there is no userData, the following would be applied:

sigData="$AMT|$TransactionId|$txCur|$txDesc|$MerchantId|$RURL$skey"

For more detail, check out RFC 2104.

Once the hash is ready, it can be used to construct a request URL and URL-encode it as follows:

https://test.tecs.at/tecsweb/tecswebmvc2.do
?mid=11450002
&sign=AA128DB70C700F809FBD1EBE74829DFA3AE1045E927586680BAE1509779BEBB0
&amt=800
&txid=1003812387331892
&txcur=EUR
&txdesc=Transaction+Description
&receiptnumber=123457
&rurl=http%3A%2F%2F127.0.0.1%3A8000%2Fpayment-response
&Date-Time-TX=20240522143437

For the full list of parameters, refer to Request URL Creation Parameters.

Before redirecting, we have to encode every parameter separately and put them all together with &.

Manual Hash Calculation is also demonstrated in NodeJS here.

🚧

Note

encodeUrl function has to replace ' ' with '+'.

Response URL

Using our PHP SDK, the response must be validated by checking if the signature is signed correctly using your merchant credentials. This is done for extra security to ensure that the merchant was the one who made the initial request URL for the respective transaction.

For example,

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

    $tecsWebResponseToken = $_GET;

    $tecsWebResponse = new \Tecs\TecsWebResponse(
        'SecretKey',   // Merchant Secret Key
        $tecsWebResponseToken
    );

    // FIRST WE CHECK IF THE RESPONSE HAS VALID SIGNATURE.
    // IF NOT THEN CREATE LOG AND REDIRECT TO OR INCLUDE ERROR PAGE.
    if (!$tecsWebResponse->isSignedCorrectly()) {
        $payloadToLog = $tecsWebResponse->getAllData();
        // Instead of echoing, you place the message to your HTML
        echo ('The result of payment has been incorrect! Please contact support.');
    }
    // IF THE RESPONSE WAS SIGNED CORRECTLY, LOG TRANSACTION RESULT AND SHOW RESULT PAGE BASED ON RESPONSE CODE
    // FOR AVAILABLE RESPONSE CODES AND MESSAGES, SEE TECSWEB DOCUMENTATION
    // YOU HAVE ACCESS TO THE RESPONSE VALUES WITH GETTERS
    else {
        $payloadToLog = $tecsWebResponse->getAllData();
        $txid = $tecsWebResponse->getTXID();
        $responseMessage = $tecsWebResponse->getResponseText();
        $responseCode = $tecsWebResponse->getResponseCode();
        // instead of echoing you place the message to your HTML.
        echo ('Transaction id ' . $txid . '; responseCode: ' . $responseCode
              . '; authorization result: ' . $responseMessage);
    }
?>

Custom Response Signature Validation

As noted in the introduction, if the merchant uses a programming language for which Bluefin TECS Web does not provide an SDK, here a pure PHP implementation is available for processing the response hash that is convertible to other languages.

<?php
    // Get the current page URL, including query string
    $redirectedUrl = $_SERVER['REQUEST_URI'];

    // Parse the URL and extract query parameters
    $parsedUrl = parse_url($redirectedUrl);
    $queryParams = [];
    if (isset($parsedUrl['query'])) {
        parse_str($parsedUrl['query'], $queryParams);
    }

    // Extract parameters required for signature calculation
    $responseCode = $queryParams['responsecode'] ?? '';
    $responseMessage = $queryParams['responsetext'] ?? '';
    $txid = $queryParams['txid'] ?? '';
    $CardReferenceNumber = $queryParams['CardReferenceNumber'] ?? ''; // Optional
    $UserData = $queryParams['User-Data'] ?? ''; // Optional
    $receivedSign = strtoupper($queryParams['sign'] ?? ''); // Received signature

    // Merchant's Secret Key
    $secretkey = "SecretKey"; // Replace with the actual secret key

    // Construct the payload in the specified order for the computed hash
    // This is how it is implemented in our PHP SDK.
    // See https://support.tecs.at/developers/ecommerce/tecsweb-php-integration/-/blob/main/src/Generator/ResponseSign.php?ref_type=heads#L45
    $payload = $responseCode . $responseMessage . $txid . $CardReferenceNumber . $UserData;

    // Convert the payload to US-ASCII encoding
    $payloadAscii = mb_convert_encoding($payload, 'US-ASCII', 'UTF-8');

    // Append the shared secret to the payload
    $payloadWithSecret = $payloadAscii.$secretkey;

    // Compute the hash using the same algorithm (SHA-256)
    $computedSign = strtoupper(hash('sha256', $payloadWithSecret));

    // Validate the computed signature against the received signature
    $isSignatureValid = ($computedSign === $receivedSign);

    if($isSignatureValid) {
              echo ('Transaction id ' . $txid . '; responseCode: ' . $responseCode
      . '; authorization result: ' . $responseMessage);
    }

    echo('Computed:' . $computedSign);
    echo('Received:' . $receivedSign);
?>

Merchant Services REST API

These are the REST API endpoints used throughout the entirety of this documentation. See API Examples and Example Use Cases.

📘

Note

Detailed API Reference documentation is available at Merchant Services REST API.

Example Endpoint Details

• /paymentTransaction

  • Required role: BO_TRANSACTIONMANAGEMENT_PAYMENT.
  • Supports authentication with bearer tokens.
  • Function: searches for a transaction by given parameters: TransactionId + terminalId + sourceId and sends a PaymentTransaction via TecsXml interface. Send XML MessageType: 0001 and when TransactionType == 'AUTHORIZATION', then TransactionOriginId: 2, else if TransactionType == 'PRE-AUTH' then TransactionOriginId: 5.
  • Request body example
    JSON

    {
      "cardNumberReference": "string",
      "transactionType": "PRE-AUTH",
      "transactionId": "string",
      "transactionDate": "20230509114131",
      "terminalId": 0,
      "clientId": 0,
      "cvc": "string",
      "amount": 0,
      "currency": "string",
      "receiptNumber": "string",
      "paymentReason": "string",
      "terminalLocation": "string",
      "password": "string",
      "ecData": "string",
      "ecrData": "string",
      "emvData": "string",
      "languageCode": "string",
      "receiptLayout": 99
    }

  • Response
    JSON

    {
      "responseCode": 0,
      "responseMessage": "string",
      "transactionId": "string",
      "messageType": "string",
      "cardNumber": "string",
      "originalTransactionId": "string",
      "amount": 0,
      "ecrData": "string",
      "emvData": "string",
      "userData": "string",
      "transactionDate": "2024-05-02T11:48:17.643Z",
      "authorizationCode": "string",
      "txType": "string",
      "acquirerName": "string",
      "acquirerId": "string",
      "cardBrand": "string",
      "merchantNumber": "string",
      "serialNumber": "string",
      "traceNumber": 0,
      "originalTraceNumber": 0,
      "svc": "string",
      "balanceAmount": "string",
      "exchangeRate": "string",
      "merchantName": "string",
      "merchantAddress": "string",
      "receiptHeader": "string",
      "receiptFooter": "string",
      "actualBonusPoints": "string",
      "exchangeFee": 0
    }

• /cancelTransaction

  • Required role: BO_TRANSACTIONMANAGEMENT_CANCEL.
  • Supports authentication with bearer tokens or basic credentials or TECS Web token.
  • Function: searches for a transaction by given parameters: originalTransactionId + terminalId + sourceId and cancels it via TecsXml interface.
  • Request body example
    JSON

    {
      "transactionId": "string",
      "messageType": "string",
      "terminalId": 0,
      "clientId": 0,
      "originalTransactionId": "string",
      "cvc": "string",
      "amount": 0,
      "currency": "string",
      "receiptNumber": "string",
      "paymentReason": "string",
      "terminalLocation": "string",
      "password": "string",
      "ecData": "string",
      "ecrData": "string",
      "emvData": "string",
      "languageCode": "string",
      "receiptLayout": 0,
      "transactionDate": "20230509114131"
    }

  • Response
    JSON

    {
      "responseCode": 0,
      "responseMessage": "string",
      "transactionId": "string",
      "messageType": "string",
      "cardNumber": "string",
      "originalTransactionId": "string",
      "amount": 0,
      "ecrData": "string",
      "emvData": "string",
      "userData": "string",
      "transactionDate": "2024-05-02T11:51:51.657Z",
      "authorizationCode": "string",
      "txType": "string",
      "acquirerName": "string",
      "acquirerId": "string",
      "cardBrand": "string",
      "merchantNumber": "string",
      "serialNumber": "string",
      "traceNumber": 0,
      "originalTraceNumber": 0,
      "svc": "string",
      "balanceAmount": "string",
      "exchangeRate": "string",
      "merchantName": "string",
      "merchantAddress": "string",
      "receiptHeader": "string",
      "receiptFooter": "string",
      "actualBonusPoints": "string",
      "exchangeFee": 0
    }

Integration Details

Authorization

TECS Web utilizes HMAC for secure authorization.

• Merchant ID (or terminal ID)
• SecretKey (namely, MerchantSecretKey - used for HMAC and URL generation)

Transaction Process

1. Create payment URL:

   • Server-side generation of a secure URL to redirect customers for payment.
   • Ensures security by using HMAC for signing parameters.

2. Customer redirection:

   • Customers are redirected to the TECS Web payment page via the generated URL to enter their payment details.

3. Payment response:

   • After payment processing, the customer is redirected back to the merchant site with transaction results appended to the return URL.

Response Handling

Responses include the transaction status, unique identifiers and any pertinent error messages or codes.

Successful Transaction Example

{
    "transactionId": "123456789",
    "status": "approved",
    "message": "Transaction successful.",
    "responseCode": 0,
}

Error Handling

Error Codes and Responses

General Response Codes

Transaction Payment Response Codes

These are possible response codes after the transaction payment is made and sent to the payment portal or gateway.

When it comes to declined transactions, there are two groups of response codes:

• Response from acquirer (ResponseCode>0 AND ResponseCode<=100)
  • These codes indicate reasons why a transaction wasn't authorized by the acquirer. Examples of reasons include exceeded limits or a blocked card. While these codes fall within the 0-100 range, their meanings can vary from one acquirer to another. When a transaction is declined, it can be helpful to show both the responsecode and responsetext to the customer for clarity.
• Response from payment gateway (ResponseCode>100 AND ResponseCode<9900)
  • These codes are generated when the TECS system conducts various checks on transaction and card details before sending the transaction to an acquirer for authorization. If any of these checks fail, the TECS system declines to process the transaction and no authorization request is sent to the acquirer.

Merchant Services Response Codes

All merchant REST services respond with a JSON object in format. For example:

{"responseCode": 0, "responseMessage": "OK"}

responseCode and HTTP status are described in the table below.

Further Information

For advanced configurations, detailed API methods and additional parameters, refer to the comprehensive API documentation provided through the Merchant Services Reference or Merchant Services Swagger.

For support and technical issues, merchants are advised to contact the TECS Web support team via the support channels specified in the merchant portal.