References

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.

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: unique per transaction

      • 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 non-zero amount initial 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' | 'dev'

  • 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
  • getAllData() -> array
    • Returns response URL parameters as an array
  • getTXID() -> string
    • Returns unique transaction ID
  • getResponseText() -> string
    • Returns responsetext from response URL
  • getResponseCode() -> string
    • Returns responsecode from response URL

Table of Transaction Types

* - 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

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'
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 &.

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

Merchant Services REST API

Detailed API documentation is available at Merchant Services REST API.

Example Endpoint Details

• /public/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
    }
    

• /public/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.

Generating Authentication Headers for REST API

There are three types of authentication methods that you can choose from before making a request to the Merchant Services REST API.

• Bearer
  • username (required): the user name for your PAM account, provided by TECS
  • password (required): the password to your PAM account, provided by TECS
• Basic
  • username (required): the user name for your PAM account, provided by TECS
  • password (required): the password to your PAM account, provided by TECS
• Web Token Authentication
  • terminalId (required): terminal Id or merchant ID, provided by TECS.
  • secret (required): the secret key, unique to each merchant, used to sign the transactions.

Bearer Token Authentication

To generate a bearer token, you simply make a POST against https://{env}-login.tecs.at/cas/oauth2.0/accessToken.

Curl example:

curl -X POST "https://test-login.tecs.at/cas/oauth2.0/accessToken?grant_type=password&client_id=tecsservice&username=username&password=password"

username, password - credentials provided to you by Bluefin TECS Payment Solutions; the same credentials are used for the PAM login.

You can, of course, grab this token from the request headers once you are logged into the PAM.

The login URL varies depending on the working environment.

Basic Authentication

Base64 is used to encode the username and password, joined by a single colon. The CAS login service is called for the given username and password in order to validate credentials.

Authorization: "Basic {Base64(username:password)}"

TECS Web Token Authentication

This token is used for verifying a TECS Web signature. The token must be hashed with the SHA-256 algorithm in HEX format and constructed in format.

sha256(transactionId|terminal|secretKey)

This is how you hash the TECS Web token in bash:

transactionId='transactionId'
terminalId='terminalId'
secretKey='secretKey'
printf '%s' "$transactionId|$terminalId|$secretKey" | sha256sum

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 portal.

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