One-way Push Notification Interface
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 |
Updated 3 months ago
This Interface serves as the module to the entire Tecs System. To make use of it, consider checking out