BigeDirect Guides - ECommerce Interface

Overview

Scope of this document

This is a technical specification for integration of a merchant’s online shop with the TECS Payment System for processing of card transactions. The integration is based on the TecsWeb interface, which is described in the later sections.

Functional overview

The application is as follows:

  1. Customer completes shopping and selects check-out / payment
  2. The webshop redirects the application flow to the TECS Web
  3. Customer enters payment (card) data to the TECS Web
  4. TECS checks the entered payment data and if OK sends a transaction to the correct acquirer.
  5. TECS receives an approval or rejection from the acquirer.
  6. The application flow is redirected to the webshop, where the response is displayed to the customer.
  7. Optional the webshop can check the transaction status through a second channel (notification module), to avoid double charge.
URL is created using the following mandatory elements:

Technical overview

When a customer chooses to check out on a merchant's online shop, the shop must redirect the customer’s web browser to the TecsWeb application using a HTTPS GET request. Parameters are sent using a preformatted URL as described in chapter 2. The data integrity in the URL is ensured by an HMAC hash which is also attached to the URL.

After the request was successfully processed the application flow is returned back to the online shop. The customer’s web browser is redirected to the shop’s return page specified by the RURL parameter in the initial request. The transaction result (Authorized, Declined, Failed, …) is included in the parameters of the return page.

For security reasons it is necessary to provide every merchant with a unique encryption key which is used for signature hash creation. This key securely exchanged and safely stored in the merchant‘s application and must not be made public to anyone else.

The shop system must keep track of the initiated transactions in case of unsuccessful requests or missing responses. The TECS system provides certain web service interfaces as described later in this document to enable the shop system to check the status of a pending request. In case the result of a request is unknown to the shop system it must initiate a cancellation request to avoid unintentional charges to the customer’s credit card.

It is recommended to open the TecsWeb page in an IFRAME embedded in the merchant’s shop or in a new window / tab with hidden address bar.

TecsWeb Virtual Card issuing and loading

TecsWeb could be used to issue new Virtual Card and load cardholder account at the merchant side using this virtual card.

Following items has to be considered during the implementation of Virtual Card loading interface:

  • To invoke virtual card issuing and loading transaction, purchase transaction of TecsWeb interface has to be invoked as defined bellow.
  • There is different URI for Virtual Card loading portal: /tecswebvc.jsp instead of /tecsweb.jsp.
  • Transaction id uniquely identifies transaction within Tecs system within MID/TID. Clients of TWVC (shops) can use defined range of TransactionId to initiate loading transaction (1 to 9 999 999) - 7N filed. TransactionId over this value is reserved for Virtual Card issuing and it's handled by TWVC platform itself.
  • All requests initiated with TWVC needs to use UserData fields 21-28 to identify the CardHolder. This identification is used for Virtual Card issuing process.
  • ReceiptNumber of the request should identify business process at the e-shop side. Should be unique per loading procedure.
  • Transaction Cancellation has to be performed according to the "TMC Transaction SOAP Webservice" document. Transaction Cancellation using browser redirection (part of cancel transaction inside TecsWeb interface specification) will be not implemented in TWVC platform.
  • Request and Response signature hash is calculated with pipe value delimiters mandatory. TecsWeb Interface specification defines them as an optional at the moment because of backward compatibility.

Creation of a URL for customer redirection

All mandatory transaction details must be sent to the TecsWeb application via the redirect URL.

Example of a formatted URL:

Parameters description

URL is created using the following mandatory elements:

Name Data Type Length Description
/tecsweb.jsp AN n/a URI of tecsweb application, must be same for every transaction
amt N 11 desired transaction amount in minor units of currency without comma
txid N 20 unique identifier of transaction
txcur AN 3 Currency code according to ISO 4217 (3 characters) eg. EUR, USD, GBP
txdesc AN 39 transaction description
receiptnumber N 20 receipt number – defined by shop for later payment reconciliation
mid N 8 merchant's identifier / terminal id
sign AN n/a transaction signature (see chapter 4)
rurl AN n/a URL of the shop return URL (see chapter 5)

The following elements are optional (when not specified, the default value is used):

Name Data Type Length Default Value Description
Date-Time-TX N 14 Current date/time Transaction date and time (Format = yyyymmddhhmmss)
TX-Source-Id N 1 1 merchant account id (for multi account systems)
Transaction-Place AN 13 ”” Describes the place (eg. WebShop name) where the transaction took place
User-Data AN 250 See chapter 2.2
lang AN 2 en Force the TecsWeb page to be displayed in a certain language. Possible vaues: en,de,it,es,fr,pl
Message-Type N 4 0001 Type of the transaction request
Txorigid N 1 2 Additional information for the transaction type as provided in parameter “msgtype”
CardNumberPost AN 80 Should be in format: "Cardnumber_expirydate" (For more details see TXML spec). If this parameter is present, tecs web page shouldn't ask cardholder to enter any data.

User-Data

The User-Data field can be used to provide additional information the shop wants to store for specific transactions. This includes information gathered for extended card holder verification or simple tags for later evaluation or statistics purposes.

The values can be completely shop specific or can be chosen from a predefined set of already defined tags and values.

Multiple values provided in the User-Data field are separated by semi-colon and should consist of a tag and a value. A semi-colon should be present at the end of the last value in the User-Data field. If it is missing, it will be added in the User-Data response field.

E.g.:

The User-Data field can also be used to trigger additional functionality like creating Installments and Recurring Payments.

E.g.:

The above example will create a recurring payment with order number (ONR) for 10,00 (IAM), executed 3 (NRI) times every 30 (IDY) days starting with 12.01.2014 (ODT).

For additional information on the usage of the User-Data fields refer to the current specification of the UserData field, which is available in Addendum_ECRInterfaceSpec.

Transaction Cancellation

When the online shop doesn't receive a response from TecsWeb within some predefined period, the transaction should be cancelled. For that purpose, the cancellation URL with valid parameters could be called. Example of remote calling of cancellation script:

Cancellation Parameters

Description of parameters:

Name Data Type Length Description
/cancel_transaction.jsp URL of cancellation script
amt N 11 transaction amount
txid N 20 transaction identifier
txcur AN 3 Currency code according to ISO 4217 (3 characters)
txdesc AN 39 transaction description
receiptnumber N 20 receipt number – defined by shop for later payment reconciliation
mid N 8 merchant identifier
sign AN n/a transaction signature (see chapter 4)
rurl AN n/a URL of the shop return URL (see chapter 5)
origTRXNum N 20 original transaction number (txid of source transaction)
Name Data Type Length Default Value Description
Date-Time-TX N 14 Current date/time Transaction date and time (Format = yyyymmddhhmmss)
TX-Source-Id N 1 1 merchant account id (for multi account systems)
Transaction-Place AN 13 ”” Describes the place (eg. WebShop name) where the transaction took place
User-Data AN 250 See chapter 2.2

Secure hash

The secure hash is a sequence of characters which ensures the authenticity of given parameters. The hash is a one-way cipher algorithm created using the SHA-1 MAC of following parameters:

  • amt
  • txid
  • txcur
  • txdesc
  • mid
  • rurl
  • User-Data (if available, see 4.1 for details)

The secure hash is created based on the above parameter values and a secret merchant key. The values of all parameters required for the hash are put together delimited by pipe character '|' in the order as shown bellow. The values in the hash must not be URL encoded.

The default algorithm in use for the Tecs test environment is SHA-1 MAC. Since this algorithm doesn’t support a designated key for encryption, the secret merchant key is appended to the values and the hash is created from the result (secret key is appended without pipe character field delimiter '|').

User-Data in Hash calculation

The User-Data parameter must not be included in the hash calculation for cancellation requests. It is only valid – if available – in payment requests (see also chapter 5 – Return URL).

Example of SHA-1 HMAC (PHP)

// input values
$amt = "100";
$txid = "1";
$txcur = "EUR";
$txdesc = "Test";
$mid = "80090000";
$rurl = “[https://your.webshop.url/ https://your.webshop.url/]”;
$User-Data = "ONR=S20110112000006;ODT=12.01.2011;IAM=1000;NRI=3;IDY=30;";
                     
// prepare values
$data = $amt ."|". $txid ."|". $txcur ."|". $txdesc ."|". $mid ."|". $rurl ."|". $User-Data;
// $data = 100|1|EUR|Test|80090000|https://your.webshop.url/|ONR=S20110112000006;ODT=12.01.2011;IAM=1000;NRI=3;IDY=30;
$key = "secretmerchantkey";
                     
$secrethash = strtoupper(sha1($data.$key));
    

When the link to the tecsweb is constructed make sure that every field that could contain encoded characters is sent as urlencoded data that the signature can match. (For example the = sign must be escaped in the User-Data example above.)

$URL = "https://test.tecs.at/tecsweb/tecsweb.jsp?amt=".$amt."&txid=".$txid;
$URL .= "&txcur=".$txcur."&txdesc=".urlencode($txdesc)."&receiptnumber=165";
$URL .= "&mid=".urlencode($mid)."&rurl=".urlencode($rurl)."&sign=".$sechash;
$URL .= "&User-Data=".urlencode($userdata);
    

As the HMAC hash algorithm returns an array of binary values, the response must be encoded using ASCII HEX encoding and converted to uppercase. In that kind of encoding every binary value of bytes is represented by string of ASCII hex representation. This can be safely attached to the URL.

Example of ASCII hex encoding implementation in java:

String ret = "";
String hexdigits[] = { "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
                        "A", "B", "C", "D", "E", "F"};
                     
for (int i = 0; i < signeddata.length; i++)
  ret += hexdigits[signeddata[i] >> 4] + hexdigits[signeddata[i] & 0xf];
    

Known implementations of HMAC algorithm are:

  • java: javax.crypto.mac (using “HmacSHA1”)
  • php: mhash (int hash, string data)

The hashing algorithm is described in RFC 2104 in detail.

Example of SHA-1 (bash)

#!/bin/bash
 
AMT='200'
TransactionId='21'
txCur='PLN'
txDesc='23 TEST TECS WEB'
MerchantId='80090051'
RURL='https://test.tecs.at/VTerm/purchase.jsp'
userData='CHI=1108;'
skey='secretmerchantkey'

sigData_old="$AMT$TransactionId$txCur$txDesc$MerchantId$RURL$userData$skey"
sigData_new="$AMT|$TransactionId|$txCur|$txDesc|$MerchantId|$RURL|$userData$skey"
                     
signature_old=`echo -n "$sigData_old" | openssl dgst -sha1 -binary | xxd -p`
signature_new=`echo -n "$sigData_new" | openssl dgst -sha1 -binary | xxd -p`
                     
S1=`echo -n $signature_old | awk '{print toupper($0)}'`
S2=`echo -n $signature_new | awk '{print toupper($0)}'`
                     
echo "Old: $S1"
echo "New: $S2"
    

Return Page

After successful processing of the transaction request, the customer is redirected back to the online shop with the result of the transaction. The customer is redirected back to the URL specified by parameter “rurl” of the transaction request. According to the response the shop can notify the customer about the result of the authorization request. For further information on possible response values and requirements for presenting the result to the customer please refer to chapter 7 “Response Codes”.

Return Parameters

Response's URL should contain the following parameters:

Name Data Type Length Description
responsecode N 4 Authorization response code (see also chapter 7)
responsetext AN 80 Description of response code
txid N 20 Transaction identifier
Date-Time-TX N 14 Transaction date and time
Authorization-number AN 9 Authorisation number generated by the authorisation centre
VU-NUMMER AN 15 Contract number of the merchant
Operator-ID AN 12 Operator-ID identifies the network processor in authorization request to the acquirer
SERIEN-NR AN 9 Card entry mode and transaction condition code
Orig-TX-ID N 20 Original transaction ID (eg. in case of a cancellation)
STAN N 6 System Trace Audit Number
Orig-STAN N 6 System Trace Audit Number of the original transaction (eg. in the case of a cancellation)
SVC N 3
User-Data AN 250 see chapter 2.2
sign AN n/a Transaction return signature
AcquirerName AN 20 Name of the acquirer which received the transaction authorisation request
CardType AN 20 Name of the card brand used by the customer (e.g. VISA, MasterCard, etc.)
CardReferenceNumber AN 40
  • 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
  • Response Signature Hash

    Signature is calculated in the same way as in the transaction creation using merchant's key from values

    • responsecode
    • responsetext
    • txid
    • CardReferenceNumber (if available)
    • User-Data (if available)
    Note: Currently is hash in response calculated without pipe delimiter placed between the parameters, however in the future this will be changed and pipe delimiter will be placed between the response parameters.

    Missing Response

    Sometimes the response might not get back to the merchant shop system because of various incidents (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 get billed by his card issuer without receiving the goods or services he 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 options how to treat this situation:

    • Automatically send a cancellation request for each transaction request with unknown result
    • Use the TECS Transaction Web Service to check the status of a transaction and react accordingly (see additional documentation “TechSpec_Transaction-Webservice-v1-1.pdf”)

    For more options and “best practice” procedures please consult your BigeDirect contact.

    Technical error as response

    If the shop receives a Technical Error (i.e. a response code >=9900, please refer to chapter 7.3), then the shop should always send a cancellation request. This is required as it is not possible to implement different reactions of the shop for all possible Technical Error ResponseCodes.

    Customer (Card holder) Notification – Optional Function

    A good practice in security is that a confirmation of transaction status is also sent in another way than simply displaying the result on the shop’s return page. For that purpose e-mail, SMS or any other distribution channel can be used.

    Refer to chapter 7 for more details on providing information on the payment result to the customer (card holder).

    Response Codes

    There are 3 groups of Response Codes:

    • "Approved"
    • "Declined"
    • "Technical Error"

    One of the above messages must be shown to the customer together with additional information as described in the following chapters.

    Please refer to the document Interface Response Codes for full list of Response Codes available in Tecs System.

    Transaction Approved

    ResponseCode: 0

    Only in case of ResponseCode=0 the transaction is positively authorized. The following 6 fields from the Response must be displayed to the customer:

    TransaktionsId:

    This is the unique transaction number per terminal sent by the shop.

    Date-Time-TX:

    Date and time of the transaction sent by the shop
    eg: "20110726165657"

    Approval-Code:

    Approval code returned by acquirer for an online authorization
    eg: "000013"

    KKG:

    This fields contains the acquirer name and card type separated by a “;” (semicolon).
    eg: "B + S CARD SERVICE;VISA"

    Betreiber-ID:

    This field contains the Acquirer Code.

    Stan:

    System Trace Audit Number, unique identification number for the transaction between Tecs and the Acquirer
    eg: 1234

    Example:

    Result: Transaction approved
    Transaction ID: nnnn
    Date Time: dd.mm.yyyy hh:mm:ss
    Approval Code: nnnn
    Acquirer: B + S CARD SERVICE
    Card Type: VISA
    Operator ID: nnnnnn
    Stan: nnnn

    In addition a notification containing this information together with the purchase details should be sent from the shop to the customer e.g. by email.

    Transaction Declined

    ResponseCode: > 0 AND < 9900

    In case of declined transactions we have to distinguish between two different groups of response codes:

  • Response from Acquirer
  • Response from Tecs Payment System
  • In any case the ResponseCode should be displayed to the customer somewhere. Additional information like ResponseText might be displayed as described below.

    Response Code from Acquirer

    ResponseCode>0 AND ResponseCode<=100''''' These response codes describe the reason why a transaction was not authorised by the acquirer.e.g.

    Limit exceeded
    Card blocked
    etc.

    Although all acquirer response codes are in the range between 0 and 100, the meaning of certain codes is not the same for all acquirers. In case of a declined transaction it might be useful to display the ResponseCode and ResponseText to the customer.

    Example:

    Result: Transaction declined
    Response Code: nnnn
    Response Text: xxxxxxxx

    Response Code from TECS

    ResponseCode > 100 AND ResponseCode < 9900

    These response codes are generated by the TECS system. The TECS system performs numerous checks on the transaction and card details before sending the transaction to an acquirer for authorisation. In case that one of those checks fails, the TECS system will decline the processing of the transaction and there will be no authorisation request to the acquirer.e.g.
    Invalid Cardnumber
    Invalid Expiry Date
    Card not accepted
    Card not accepted terminal
    etc.

    Example:

    Result: Transaction declined
    Response Code: nnnn
    Response Text: xxxxxxxx

    Technical Error

    ResponseCode: >= 9900 AND < 9999

    This range of Response Codes covers technical problems that occurred when the transaction is processed. This response codes are returned by either TECS Engine or the TECS XML frontend.
    e.g.
    Network problems
    Database errors
    Connectivity problems
    Communication errors etc.

    Example:

    Result: Technical Error
    Response Code: nnnn
    Response Text: xxxxxxxx