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

Transaction TypeMessage-TypeTxorigidDescription
PRE-AUTH0901 | 00015This type of transaction reserves a certain amount on the customer's card but does not complete the payment immediately. It's commonly used in industries like hospitality (e.g. hotels, car rentals) where final charges may vary based on services used.
*OFFLINE AUTHORIZATION09016This is similar to pre-authorization but is processed offline, meaning the authorization is done without an immediate connection to the card issuer. It's used in situations where online authorization is not possible, such as in-flight purchases.
AUTHORIZATION0001NOT 5This type of transaction authorizes a payment amount and checks if the customer's account has sufficient funds for the transaction. It's a standard authorization for a purchase.
REFUND0911 | 0011Refund transactions are used to return funds to the customer's card, typically for returned goods or canceled services.
CAPTURE0013 | 00174A capture transaction completes a pre-authorized AUTHORIZATION transaction, transferring the reserved funds to the merchant's account. It's the final step in processing a pre-authorization.
CANCELLATION0013NOT 4A cancellation transaction cancels a pre-authorization or an authorization before it is captured. It releases the reserved funds back to the cardholder.
TECHNICAL CANCELLATION0017NOT 4Similar to cancellation, a technical cancellation is used to release reserved funds without completing the transaction. It's often used in cases of technical errors or system issues.
*REVERSAL0420NOT 4A reversal transaction cancels a previous authorization or capture request. It's used to void a transaction that hasn't been completed yet, such as in the case of a payment error.
*AUTHORIZATION+TIP0907 | 0007This transaction type includes an additional tip amount with the authorization, commonly seen in industries where tipping is customary, such as restaurants.
*TIP0909 | 0009A tip transaction is a standalone transaction to add a tip amount to a previously authorized transaction, typically done in scenarios where tipping is separate from the initial payment authorization.

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

NameData TypeLengthDescription
/tecswebmvc_start.doANn/aURI of TECS Web application, must be same for every transaction.
amtN11Desired transaction amount in minor units of currency without comma.
txidN20Unique identifier of transaction.
txcurAN3Currency code according to ISO 4217 (3 characters) eg. EUR, USD, GBP.
txdescAN39Transaction description.
receiptnumberAN20Receipt number – defined by shop for later payment reconciliation.
midN8Merchant's identifier or terminal ID.
signANn/aTransaction signature.
rurlANn/aURL of the shop return URL.
Date-Time-TXN14Transaction date and time (format = yyyymmddhhmmss).

Optional Parameters

NameData TypeLenDefault valueDescription
ecdataAN""Type of recurring payment: "INST;" | "RECU;" | "CIT;". Note that this parameter is required in the production environment for recurring payments. See PHP SDK REFERENCE.
TX-Source-IdN11Merchant account ID (for multi-account systems).
Transaction-PlaceAN13""Describes the place (e.g. webshop name) where the transaction took place.
User-DataAN250""User-specific data. See PHP SDK REFERENCE.
langAN2enForce the TECS Web page to be displayed in a certain language.
Message-TypeN40001Type of the transaction request. For full list of message types, check out Table of Transaction Types.
TxorigidN12Additional information on the transaction type as provided in the parameter Message-Type.
origTRXNumN20Original transaction number (txid of source transaction).
CardNumberPostAN80Should be in the format "Cardnumber_expirydate" (for more details, see TXML spec). If this parameter is present, the TECS Web page shouldn't ask the cardholder to enter any data.

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.

NameData TypeLengthDescription
responsecodeN4Authorization response code (see also chapter 7).
responsetextAN80Description of response code.
txidN20Transaction identifier.
Date-Time-TXN14Transaction date and time.
Authorization-numberAN9Authorization number generated by the authorization centre.
VU-NUMMERAN15Contract number of the merchant.
Operator-IDAN12Operator-ID identifies the network processor in authorization request to the acquirer.
SERIEN-NRAN9Card entry mode and transaction condition code.
Orig-TX-IDN20Original transaction ID (e.g. in case of a cancellation).
STANN6System trace audit number.
Orig-STANN6System trace audit number of the original transaction (e.g. in the case of a cancellation).
SVCN3
User-DataAN250User-specific data. See PHP SDK REFERENCE.
signANn/aTransaction return signature.
AcquirerNameAN20Name of the acquirer that received the transaction authorization request.
CardTypeAN20Name of the card brand used by the customer (e.g. VISA, MasterCard, etc.).
CardReferenceNumberAN40See below.

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:

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

AlgorithmSignature Length
SHA-22456
SHA-25664
SHA-38496
SHA-512128

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.

EndpointMethodDescription
/public/statusTransactionPOSTRetrieve the status of a transaction.
/public/cancelTransactionPOSTCancel a specific transaction.
/public/refundTransactionPOSTRefund a processed transaction.
/public/preAuthCompletionTransactionPOSTComplete a pre-authorized transaction.
/public/paymentTransactionPOSTInitiate a payment transaction.
/public/transactionHistoryPOSTSearch for transactions by specified parameters.

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

Environment NameEndpoint
Development environmenthttps://dev-login.tecs.at
Testing environmenthttps://test-login.tecs.at
Production environmenthttps://login.tecspayment.com

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

CodeDescription
200Success.
400Bad request - invalid parameters.
401Unauthorized - authentication failure.
500Internal server error - server-side error.

Transaction Payment Response Codes

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

Code NameCodePossible Causes
Approved0
DeclinedSee belowInvalid card number, invalid expiry date, invalid card verification value, card not accepted, etc.
Technical Error>=9900 AND <9999Network problems, database errors, donnectivity issues, dommunication errors, etc.

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.

HTTP StatusResponse CodeDescription
2000OK.
50025000Internal server error.
40025001OAuth interaction failed, e.g. failed to call UserProfile service.
40125002Invalid OAuth token.
40325003Unauthorized, e.g. missing required role.
40025004Bad request, invalid parameter supplied.
40325005User inactive.
50025006Corporate account error.
40025007Terminal not found.
40025008Mandator not found.
40025009Invalid template.
40025010Invalid country.
40025011TECS company not found.
50025012Data integrity error, e.g. some DB constraint was violated when a template was being processed.
50025013Data access error, e.g. a DB error occurred when a template was being processed.
20025014Terminal already registered.
40025015Transaction not found.
40025016VU nummer must be unique.
20025017Card blacklisted.
50025018CAS user management error.
40325019Missing role.
40025020Missing parameter.
40025021Record already exists.

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.


What’s Next

On completion of reading TecsWeb documentation, we suggest you next check out the following