API Examples
JSON Web Service
Transaction data can be handled on either the client-side or the server-side. In this example, we handle all data on the client side (browser). However, the client (shop) has the flexibility to choose which aspects of the transaction data it wants to handle on the client-side versus the server-side.
Server Side
<?php
require '/path-to/tecsweb-php-lib/loader.php'; // composer: require 'vendor/autoload.php';
// Data provided by client (browser)
$data = json_decode(file_get_contents('php://input'), true);
/************************************/
/** Place for preparing transaction */
/************************************/
// header("Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'");
$tecs = new \Tecs\TecsWeb(
'SecretKey', // Private secret key provided by TECS
'MerchantId', // Merchant ID provided by TECS
'https://test.tecs.at/tecsweb/tecswebmvc_start.do' // URL of payment portal
);
try {
$url = $tecs->createSignedUrl([
\Tecs\TecsWeb::AMOUNT => $data[\Tecs\TecsWeb::AMOUNT],
\Tecs\TecsWeb::TX_ID => $data[\Tecs\TecsWeb::TX_ID],
\Tecs\TecsWeb::TX_CURRENCY => $data[\Tecs\TecsWeb::TX_CURRENCY],
\Tecs\TecsWeb::TX_DESC => $data[\Tecs\TecsWeb::TX_DESC],
\Tecs\TecsWeb::RECEIPT_NUMBER => $data[\Tecs\TecsWeb::RECEIPT_NUMBER],
\Tecs\TecsWeb::RETURN_URL => $data[\Tecs\TecsWeb::RETURN_URL],
\Tecs\TecsWeb::TX_DATE_TIME => $data[\Tecs\TecsWeb::TX_DATE_TIME]
]);
// Create successful JSON response
header("Content-Type: application/json");
// header("Content-Security-Policy: frame-ancestors 'none'");
exit(json_encode([
'tecsWebRequestToken' => $url->getSignedUrl()
]));
} catch (\Exception $e) {
// Create JSON response on error
header("Content-Type: application/json");
exit(json_encode([
'error' => $e->getMessage()
]));
}
?>
Client Side
<html>
<head>
<script src="https://test.tecs.at/tecsweb/js/tecsweb.js"></script>
</head>
<body>
<div id="tecsweb-payment-wrapper"></div>
<script>
const padZero = (num) => {
return String(num).padStart(2, '0');
}
const makeTransactionDateTime = () => {
const currentDate = new Date();
const year = currentDate.getFullYear();
const month = padZero(currentDate.getMonth() + 1);
const day = padZero(currentDate.getDate());
const hours = padZero(currentDate.getHours());
const minutes = padZero(currentDate.getMinutes());
const seconds = padZero(currentDate.getSeconds());
const formattedDate = `${year}${month}${day}${hours}${minutes}${seconds}`;
return formattedDate;
}
const data = {
[TecsWeb.AMOUNT]: '100',
[TecsWeb.TX_ID]: '1000017864914',
[TecsWeb.TX_CURRENCY]: 'EUR',
[TecsWeb.TX_DESC]: 'Test TecsWeb',
[TecsWeb.RECEIPT_NUMBER]: '123456',
[TecsWeb.RETURN_URL]: 'https://tecsweb-iframe-test.loc/payment-response.php',
[TecsWeb.BACKEND_SIGN_URL]: 'https://tecsweb-iframe-test.loc/get-tecsweb-token.php',
[TecsWeb.TX_DATE_TIME]: makeTransactionDateTime()
};
TecsWeb.getSignedUrl(data).then(function (response) {
// create a button or an iframe with response.data.tecsWebRequestToken
});
</script>
</body>
</html>
BACKEND_SIGN_URL
is the endpoint of the JSON web service, which, in successful cases, returns TecsWebRequestToken.
TecsWeb.getSignedUrl(data)
- This function is especially useful in fetching the
tecsWebRequestToken
from the server side that is written in a language that the TECS Web SDK does not support such asC++
,Rust
,Python
, etc. In the Example Use Cases, we set up a NodeJS server walking you through this scenario.
Transaction History
It is best to run a pagination query before performing a transaction cancellation or similar transaction operation. This is because the pagination query delivers some of the body parameters required for the cancellation request payload, such as originalTransactionId
, transactionAmount
, transactionCurrency
, receiptNumber
, terminalId
, and clientId
.
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/transactionHistory
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"pagination": { "page":0, "size":15 },
"transactionDateFrom":"2024-05-01T00:00:00.000",
"transactionDateTo":"2024-05-24T23:59:59.999"
}`
}
For the full JSON schema, refer to Swagger Docs.
This request returns all the transactions made between transactionDateFrom
and transactionDateTo
with pagination
.
Specifying referencedTransactionId
returns a history of operations performed on that transaction. Most notably, these can include a record of captured transactions, where referencedTransactionId
is the transactionId
of an authorization transaction. For example, these are the following transaction types that can occur in this history record of a referenced transaction (under the transactionType
field): "PRE-AUTH" | "OFFLINE AUTHORIZATION" | "AUTHORIZATION" | "REFUND" | "CAPTURE" | "CANCELLATION" | "TECHNICAL CANCELLATION" | "REVERSAL" | "AUTHORIZATION+TIP" | "TIP"
.
For example,
{
"pagination": { "page": 0, "size": 25},
"referencedTransactionId": "20240822205621368000",
"terminalId": {terminalId}
}
In the request body above,
terminalId
is optional but it helps query the transactions processed under a specific terminal id.
Transaction Cancellation
For transaction cancellation, we use the Merchant Services REST API.
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/cancelTransaction
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"messageType": "0013",
"clientId": 1,
"transactionId": "{transactionId}",
"transactionDate":" {transactionDate}",
"amount": {transactionAmount},
"currency":"EUR",
"originalTransactionId": "{originalTransactionId}",
"paymentReason": "Immediate cancellation",
"receiptNumber": "{receiptNumber}",
"terminalId": "{terminalId}"
}`
}
Make sure the
terminalId
always matches the one where you processed the transaction. Otherwise, you will get"Transaction not found"
.
For the full JSON schema, refer to Swagger Docs.
Body parameters:
-
messageType
(string) (required) - refer to Table Of Transaction Types. -
transactionId
(string) (required) is usually put together withtransactionDate
and a random three digit number e.g."20240502170" + "021"
. -
transactionDate
(string) (required) is in this format:yyyymmddhhmmss
. Everything is padded by leading zeros if necessary. -
originalTransactionId
(string) (required) - the id of the transaction to cancel. For Transaction Payment, this goes under thetransactionId
field.
TECS Transaction Status
The merchant services REST API is usually used to get a transaction status.
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/statusTransaction
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"sourceId": 1,
"transactionId": "{transactionId}",
"terminalId": "{terminalId}"
}`
}
For the full JSON schema, refer to Swagger Docs.
PHP SDK
The PHP SDK also supports class TecsWebTransactionStatus
to get the transaction status on the server side. Essentially, this is a REST API wrapper set up with the php-curl
utility and curl_init
. In other words, it is straightforward to set up REST API calls that the PHP SDK doesn't support on the server side.
<?php
require 'vendor/autoload.php';
$tecs_web_transaction_status = new \Tecs\TecsWebTransactionStatus(
'merchantId', // terminal ID
'secretKey',
'test',
);
$transaction_status = $tecs_web_transaction_status->getTransactionStatus('originalTransactionId');
print_r($transaction_status);
?>
Transaction Payment
Bluefin TECS also uses the merchant services REST API to support the processing of transaction payments. This is particularly useful for recurring payments, as pointed out in the Use Cases. With the transactionType
of PRE-AUTH
, transactions performed with this endpoint are pending to be completed/captured in the step below. For the distinction between PRE-AUTH
and AUTHORIZATION
, refer to Table of Transaction Types.
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/paymentTransaction
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"cardNumberReference": "{cardNumberReference}",
"transactionType": "{transactionType}",
"transactionId": "{transactionId}",
"transactionDate": "{transactionDate}",
"terminalId": {terminalId},
"clientId": 1,
"cvc": "",
"amount": {transactionAmount},
"currency": "EUR",
"receiptNumber": "{receiptNumber}",
"paymentReason": "test sale",
"terminalLocation": "BA",
"password": "{terminalPassword}",
"ecData": "",
"ecrData": "",
"emvData": "",
"languageCode": "EN",
"receiptLayout": 99
}`
}
For the full JSON schema, refer to Swagger Docs.
Body parameters:
-
transactionType
(string) (required) -"PRE-AUTH" | "AUTHORIZATION"
-
ecData
(string): For recurring processing, this property is required in the production environment. It specifies the nature of the recurring transaction and helps identify it accordingly. In the testing environment, this value is ignored. The enumerations for this parameter are as follows:-
"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.
-
Pre-Authorization Completion
Payments (sale or PRE-AUTH) are processed by calling the REST API. This sends the payment to the acquirer for authorization and returns the response to the webshop, where the application flow is completed. In other words, this request captures a PRE-AUTH
transaction.
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/preAuthCompletionTransaction
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"transactionId": "{transactionId}",
"transactionDate": "{transactionDate}",
"terminalId": {terminalId},
"clientId": 1,
"amount": {transactionAmount},
"currency": "EUR",
"receiptNumber": "{receiptNumber}",
"paymentReason": "test completion",
"originalTransactionId": "{originalTransactionId}"
}`
}
For the full JSON schema, refer to Swagger Docs.
Transaction Refund
Request Configuration
POST https://{-*}.tecs.at/merchantservices/public/refundTransaction
{
method: "POST",
headers: {
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{
"messageType": "0011",
"transactionId": "{transactionId}",
"transactionDate": "{transactionDate}",
"terminalId": {terminalId},
"clientId": 1,
"amount": {transactionAmount},
"currency": "EUR",
"receiptNumber": "{receiptNumber}",
"paymentReason": "Order Errors",
"originalTransactionId": "{originalTransactionId}"
}`
}
For the full JSON schema, refer to Swagger Docs.
originalTransactionId
(string) (required) - the id of the transaction to refund.
Updated 19 days ago