Flow

After each transaction, the TECS processing engine sends a JSON-formatted one-way push notification to the 3rd Party Portal via REST API. If the portal fails to receive the notification, TECS will automatically resend it multiple times per day.

The 3rd Party Portal, also referred to as the merchant's server, is supposed to be setup and built by the merchant. This merchant server serves as a "webhook" for the TECS Engine. The customer specifies the URL, and then Bluefin TECS configure the merchant/terminal identifier and TECS Engine so that the push notifications can ultimately be forwarded back to the server URL. Once the workflow below is completed, the TECS Engine automatically forwards the one-way push notification payload to the client server URL.

API Reference

Version: 1.16.5

One-way Push Notification

This notification contains crucial transaction data that the merchant can utilize for various purposes. Once received, the merchant can process the payload according to their specific requirements. For instance, the data can be used to generate a reconciliation report, update inventory, track sales metrics, or trigger automated responses within the merchant's system.

The push notification mechanism ensures real-time data transfer, allowing the merchant to maintain up-to-date records and perform timely actions based on the transaction information. This integration not only enhances operational efficiency but also provides the flexibility to customize data handling to align with the merchant's business processes and reporting needs.

By leveraging these notifications, merchants can streamline their workflow, improve data accuracy, and gain valuable insights into their transaction activities, ultimately leading to better decision-making and enhanced customer service.

Request Example

This is an example of a one-way push notification sent by the TECS Engine to the 3rd Party Portal.

{
    "transactionSeqNumber": 5388980,
    "transactionId": "20191106102327",
    "transactionType": "AUTHORIZATION",
    "merchantNumber": "000000123456789",
    "merchantName": "Test Merchant",
    "terminalId": 88091113,
    "acquirerTerminalId": "U88091113",
    "acquirerName": "Test acquirer",
    "amount": 100,
    "currency": "EUR",
    "transactionDate": "2019-11-06T10:23:27+0000",
    "transactionServerDate": "2019-11-06T10:23:31+0000",
    "authorizationDate": "2019-11-06T10:23:31+0000",
    "transactionClearingDate": "2019-11-07T01:00:31+0000",
    "authorizationCode": "00734127",
    "responseCode": 0,
    "responseMessage": "Authorized",
    "responseCodeFromAS": "000",
    "receiptNumber": "00000000000000000123",
    "cardNumber": "478076XXXXXX9570",
    "cardExpiration": "2302", 
    "paymentReason": "Test payment",
    "cardBrand": "VISA",
    "retrievalReferenceNumber": "931010031463",
    "traceNumber": 546783,
    "clientId": 1,
    "emvApplicationId": "A0000000031010",
    "emvApplicationLabel": "applicationLabel",
    "cvm": "NO_CVM",
    "applicationCryptogram": "77B681F0263B07EE",
    "serviceCode": "000",
    "transactionSource": "CARD",
    "cardEntry": "CTLS",
    "terminalLocation": "Tecs Test Wien",
    "originalTransactionId": null,
    "clearingStatus": "READY",
    "clearingAmount": 100, 
    "clearingCurrency": "EUR",
    "clearingProcessedDate": null,
    "clearingBatchId": null,
    "clearingDate": "2019-11-07T01:35:53+0000",
    "tipAmount": null,
    "originalTerminalId": null,
    "originalClientId": null,
    "settlementStatus": "NOT_SETTLED",
    "terminalEndOfDayDate": null
}

Request Parameters

Parameter	Type	Description
transactionSeqNumber	int	Transaction sequence number assigned by TECS processing engine.
transactionId	numeric (20N)	Transactionid assigned by the transaction initiator (web-shop, ECR, terminal, etc.)
transactionType	string	Type of transaction (For instance, `"AUTHORIZATION"`, `"REFUND"`, `"PRE-AUTH"`, `"CAPTURE"`, `"REVERSAL"`, `"ADVICE"`, `"AUTHORIZATION+TIP"`, `"TIP"`)
merchantNumber	string	Merchant contract number with the acquirer
merchantName	string	Merchant name
terminalId	numeric	TECS terminalid provided by Bluefin TECS
originalTerminalId	numeric	Original terminal identifier - used for transactions such as `Refund`, `Capture`, `Cancel`.
acquirerTerminalId	string	Acquirer terminalID
acquirerName	string	Acquirer name
amount	numeric	Transaction amount in cents
currency	string	Transaction currency
transactionDate	datetime	Date time of transaction in merchant's timezone given by transaction initiator: ISO 8601 Format.
transactionServerDate	datetime	Date time of transaction in the TECS processing engine database: ISO 8601 Format.
authorizationDate	datetime	Date time - the date TECS processing engine received transaction approval from the acquirer. ISO 8601 Format
transactionClearingDate	datetime	Date time - the date transaction is set to be cleared by TECS processing engine. ISO 8601 Format
authorizationCode	string	Approval code
tecsengineResponseCode	int	TECS processing engine response code (0 - transaction is approved, all other codes - declined)
tecsengineResponseText	string	TECS processing engine response text
responseCodeFromAS	string	Acquirer/card scheme response code
receiptNumber	string	Receipt number generated by transaction initiator
cardNumber	string	Masked card number
cardExpiration	string	Card expiration
paymentReason	string	Payment reason issued by the transaction initiator
cardBrand	string	Card brand such as `"VISA"`, `"MASTERCARD"`, `"AMEX"`, `"AliPay"`, etc.
retrievalReferenceNumber	string	Retrieval reference number generated by TECS processing engine. This is usually used for the purposes of Unique Identification, Tracking and Retrieval, Customer Support, Auditing and Reporting.
traceNumber	numeric (6N)	Unique identifier used within the TECS Payment System to track and audit transactions
clientId	int	Identifier for managing merchant’s bank accounts (MBAI).
originalClientId	numeric	Original client identifier - used for transactions such as `Refund`, `Capture`, `Cancel`.
emvApplicationId	string	EMV applicationid
emvApplicationLabel	string (16AN)	EMV tag 50 - application label
cvm	string	Consumer verification method (e.g. `"PIN"`, `"SIGNATURE"`, `"NO_CVM"`, `"3DS"`)
applicationCryptogram	numeric	Application cryptogram
serviceCode	numeric (3N)	Service code from the card
transactionSource	string	Origin (e.g. `"CARD"`, `"ECOMMERCE"`, `"MANUAL"`)
cardEntry	string	Card Entry (e.g. `"CHIP"`, `"MAG"`, `"CTLS"`, `"MOTO"`, `"FALLBACK"`)
terminalLocation	string	Terminal location
originalTransactionId	numeric (20N)	Original transactionid, used for transactions that have subsequence (For instance, Refund, Capture, Reversal, Cancel)
clearingStatus	string	Clearing status of the original transaction: OPEN (awaiting authorization), READY (authorized and ready for clearing), IN_PROGRESS (clearing in progress), SUCCESSFUL (cleared), ERROR (clearing error), CANCELLED (cancelled).
clearingAmount	numeric	Clearing amount in cents of original transaction
clearingCurrency	string	Clearing currency of original transaction
clearingProcessedDate	datetime	Date time, when original transaction was cleared by TECS processing engine.
clearingBatchId	string	Acquirer clearing batchid
clearingDate	datetime	Date time - the date transaction is set to be cleared by TECS processing engine. ISO 8601 Format
tipAmount	numeric	Tip amount in cents
settlementStatus	string	Settlement status of transactions: `"SETTLED"` or`"NOT_SETTLED"`
terminalEndOfDayDate	datetime	Date time that the end of day was initiated by terminal operator. ISO 8601 Format

Response

Determined by the 3rd Party Portal ( merchant's server )

Example Response:

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

Response Parameters

Parameter	Type	Description
responseCode	int	Response code (0 = OK, otherwise an error code).
responseMessage	string	Human readable response code representation.

Status Transaction API

As opposed to being sent back to the merchant's server for processing, the one-way push notification can also be received via the Merchant Services REST API, which then communicates with the TECS Payment Gateway. In other words, we are reusing the notification module via Merchant Services REST API.

There are two ways to get the transaction status via status transaction api:

with transactionSeqNumber parameters only
with the combination of sourceId, transactionId, terminalId

Request

POST https://{-*}.tecs.at/merchantservices/public/statusTransaction

{
    method: "POST",
    headers: {
      "Authorization": "{authKey}",
      "Content-Type": "application/json",
    },
    body: `{
      "transactionSeqNumber": "{transactionSeqNumber}"
    }`
}

For the two other ways to get the transaction status, refer to TECS Transaction Status.

Response

{
    "responseCode": 0,
    "responseMessage": "OK",
    "transactionSeqNumber": 5388980,
    "transactionId": "20191106102327",
    "transactionType": "AUTHORIZATION",
    "merchantNumber": "000000123456789",
    "merchantName": "Test Merchant",
    "terminalId": 88091113,
    "acquirerTerminalId": "U88091113",
    "acquirerName": "Test acquirer",
    "amount": 100,
    "currency": "EUR",
    "transactionDate": "2019-11-06T10:23:27+0000",
    "transactionServerDate": "2019-11-06T10:23:31+0000",
    "authorizationDate": "2019-11-06T10:23:31+0000",
    "transactionClearingDate": "2019-11-07T01:00:31+0000",
    "authorizationCode": "00734127",
    "tecsengineResponseCode": 0,
    "tecsengineResponseText": "Authorized",
    "responseCodeFromAS": "000",
    "receiptNumber": "00000000000000000123",
    "cardNumber": "478076XXXXXX9570",
    "cardExpiration": "2302",
    "paymentReason": "Test payment",
    "cardBrand": "VISA",
    "retrievalReferenceNumber": "931010031463",
    "traceNumber": 546783,
    "clientId": 1,
    "emvApplicationId": "A0000000031010",
    "emvApplicationLabel": "applicationLabel",
    "cvm": "NO_CVM",
    "applicationCryptogram": "77B681F0263B07EE",
    "serviceCode": "000",
    "transactionSource": "CARD",
    "cardEntry": "CTLS",
    "terminalLocation": "Tecs Test Wien",
    "originalTransactionId": null,
    "clearingStatus": "READY",
    "clearingAmount": 100, 
    "clearingCurrency": "EUR",
    "clearingProcessedDate": "2019-11-07T02:10:31+0000",
    "clearingBatchId": "34543535",
    "clearingDate": "2019-11-07T01:00:31+0000",
    "tipAmount": null,
    "settlementStatus": null,
    "originalTerminalId": null,
    "originalClientId": null,
    "terminalEndOfDayDate": null
}

Response Parameters

The response parameters are the same as One-way Push Notification Parameters just with two additional parameters to indicate the response.

Parameter	Type	Description
responseCode	int	Transaction status response code
responseMessage	string	Transaction status response text/message