PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

Merchant & Terminal Registration API

Suggest Edits

The TECS Merchant and Terminal Registration API enables users to:

  • Automatically register new merchants and terminals on the TECS Platform
  • Receive email and SMS notifications upon successful merchant registration
  • Deactivate terminals if they are broken, stolen, or otherwise compromised

Overview


For merchant registration and the registration of the first terminal, use the Merchant and Terminal Registration call, registerNewMerchant. The caller must provide the packageid, which is supplied by TECS and is constant for a specific terminal type.

The caller needs to store the packageorderuuid received as a response parameter from the registerNewMerchant call. This parameter must be provided as an input inregisterAdditionalTerminal or registerAdditionalAcquiring call if the caller wants to register an additional terminal or acquirer for an existing merchant.

If a terminal is broken, stolen, or otherwise compromised, it needs to be deactivated using the deactivateTerminal call. A replacement terminal can be registered by calling registerAdditionalTerminal.

API Endpoints

Register a New Merchant and Terminal

The registerNewMerchant call enables the user to register both a merchant and an associated terminal.

Example Request

curl -X POST \
    "https://test.tecs.at/merchantportalws/registerNewMerchant" \
    -u User1:Password1 \
    -H "accept: application/json" \
    -H "content-type: application/json" \
    -d "{
        \"merchant_name\": \" Test merchant\", 
        \"business_reg_number\": \"345345345\",
        \"country\": \"SVK\",
        \"state\": null,
        \"city\": \"Bratislava\",
        \"street\": \"Palisady 12\",
        \"zipcode\": \"81106\", 
        \"packageid\": \"87055654-3158-42fc-9838-74f1fc77f42b\",
        \"productid\": \"1749b8f1-d049-45e0-86f2-762d803bb286\",
        \"productid_acquirer\": \"874d84a8-a6f4-47fa-b594-944593fc394b\", 
        \"terminalid_acquirer\": \"66000001\",
        \"terminal_location\": \"Palisady 12 BA\",
        \"terminal_country_code\": \"SVK\",
        \"terminal_language_code\": \"EN\",
        \"terminal_serial_number\": \"325-320-924\",
        \"currency\": \"EUR\",
        \"vu-nummer\": \"9034520\",
        \"merchant_category_code\": \"5999\",
        \"sorting_code\": \"123456\",
        \"account_number\": \"123456\",
        \"username\": \"testuser\",
        \"password\": \"testpassword\",
        \"merchant_email\": \"[email protected]\",
        \"merchant_phone_number\": \"+421910876567\",
        \"user_email\": \"[email protected]\",
        \"user_phone_number\": \"+421910876568\",
        \"web_shop_url\": \"https://www.tecs.at\"\
         \"additional_data\": 
            { 
            \"firstname\": \"John\", 
            \"surname\": \"Doe\", 
            \"type\": \"tx-300\", 
            \"version\": \"v1.2.3\" 
            }
        }"

Request Parameters

ParameterTypeRequiredDescription
merchant_namestring (25AN)requiredThe company name as it is officially incorporated
business_reg_numberstring (9AN)requiredMerchant business registration number as stated in company registry
countrystring (3AN)requiredMerchant's address: country; Must be in "ISO-3166 ALPHA-3" format
statestringoptionalMerchant's address state
citystringrequiredMerchant's address city
streetstringrequiredMerchant's address street and house number
zipcodestringrequiredMerchant's address postal code
packageidstringmandatoryIdentifier of package in Tecs processing engine provided by TECS.
productidstringoptionalOptional identifier of product in Tecs processing engine provided by TECS. If not specified, default product is used as defined in package definition.
productid_acquirerstringoptionalOptional identifier of product provided by acquirer; if not specified, default product is used as specified in package definition
terminalid_acquirerstringoptionalTerminal ID provided by the acquirer
terminal_locationstringmandatoryTerminal location
terminal_country_codestring (3AN)mandatoryTerminal country code; must be in "ISO-3166 ALPHA-3" format
terminal_language_codestring (2AN)mandatoryTerminal language code; must be in "ISO 639-1" format
terminal_serial_numberstring (50AN)conditionalTerminal serial number
currencystring (3AN)mandatoryTransaction currency; must be in "ISO 4217" format
vu-nummerstring (15AN)mandatoryMerchant contract number with acquirer
merchant_category_codeint (4N)mandatoryMerchant category code
sorting_codenumeric (9N)optionalSorting code provided by acquirer
account_numbernumeric (9N)optionalAccount number provided by acquirer
usernamestringoptionalMerchant username for MPOS; if it's not provided, it will be generated by TECS and provided as a response parameter
passwordstringoptionalMerchant password for MPOS; if it's not provided, it will be generated by TECS and provided as a response parameter
merchant_emailstringoptionalMerchant's email address for receiving notifications
merchant_phone_numberstringoptionalMerchant's phone number for receiving notifications; Must be in international format: '+' country code phone number

Example: +421910711234
user_emailstringoptionalEmail address of the user acting on behalf of the merchant
user_phone_numberstringoptionalPhone number of the user acting on behalf of the merchant; Must be in international format: '+' country code phone number

Example: +421910711234
web_shop_urlstringoptionalThe web-shop url address for eCommerce terminal
additional_dataarray of (parameter:value)optionalAdditional information for acquirer

Example Response

{
    "response_code": "0",
    "response_text": "OK",
    "packageorderuuid": "16acb5a4-e573-423c-a024-fae90ea45d70",
    "terminalid": "88091104",
    "corporateuuid":"fd1b6927-9105-4e2a-92c0-07c6da71624d",
    "username": "testuser",
    "password": "testpassword"
}

Response Parameters

ParameterTypeDescription
responseCodeintResponse code (0 = OK, otherwise an error code)
responseMessagestringHuman readable error description
packageorderuuidstringUnique identifier; can be used to register additional terminals for an existing merchant
terminalidnumericThe terminal identification code provided by TECS Platform
corporateuuidstringTECS-generated corporate identification code
usernamestringTECS-generated merchant username if not provided in request
passwordstringTECS-generated merchant password if not provided in request

Error Codes

Error CodeError Message
24000You don't have permissions (state User_HasNotRole)
24001You don't have permissions (state Mandator_IsNotTheSame)
24012Mandatory fields are not filled %1$s (state MandatoryFields_AreNotFilled)
24014with arbitrary message (state Unexpected_Exception)
24015merchant_name (must be present, in correct format)
24016business_reg_number (must be present, in correct format)
24017country (must be present, in correct format)
24018city (must be present, in correct format)
24019street (must be present, in correct format)
24020zipcode (must be present, in correct format)
24021packageid (must be present, in correct format)
24022terminal_location (must be present, in correct format)
24023terminal_country_code (must be present, in correct format)
24024terminal_language_code (must be present, in correct format)
24025terminal_serial_number (must be present, in correct format)
24026currency (must be present, in correct format)
24027vu_nummer (must be present, in correct format)
24031merchant_category_code (must be present, in correct format)
24032merchant_email (incorrect email address format)
24033merchant_phone_number (incorrect phone number format)
24034user_email (incorrect email address format)
24035user_phone_number (incorrect phone number format)
25000INTERNAL_SERVER_ERROR
25001OAUTH_INTERACTION_FAILED
25002OAUTH_INVALID_TOKEN
25003UNAUTHORIZED
25004BAD_REQUEST
25005USER_INACTIVE
25006CORPORATE_ACCOUNT_ERROR
25007TECS_TERM_NOT_FOUND
25008MANDATOR_NOT_FOUND
25009INVALID_TEMPLATE
25010INVALID_COUNTRY
25011TECS_COMPANY_NOT_FOUND
25012DATA_INTEGRITY_ERROR
25013DATA_ACCESS_ERROR
26030PIN_REQUIREMENT_FAILED
26031PIN_ALREADY_EXISTS
26032CONSUMER_NOT_PREREGISTERED_STATUS
26033CONSUMER_EXISTS
26034WRONG_PHONE_FORMAT
26097General_ERROR
26098INVALID_INPUT
26099INVALID_CREDENTIALS
27000INVALID_INPUT
27002INVALID_PERMISSION
27005BUSINESSREGNO_HAS_TO_BE_UNIQUE
27006TID_HAS_TO_BE_UNIQUE
27007WRONG_TID_FORMAT
27008WRONG_PHONE_FORMAT
27010WRONG_EMAIL_FORMAT

Register a Terminal for an Existing Merchant

The registerAdditionalTerminal call registers a terminal to an existing merchant.

Example Request

curl -X POST \
    "https://test.tecs.at/merchantportalws/registerAdditionalTerminal" \
    -u User1:Password1 \
    -H "accept: application/json" \
    -H "content-type: application/json" \
    -d "{ \"packageorderuuid\": \"dccb9a6a-b02c-46e3-aef3-a28f0b7bf993\",
        \"productid\": \"1749b8f1-d049-45e0-86f2-762d803bb286\",
        \"terminal_location\": \"Palisady 12 BA\",
        \"terminal_country_code\": \"SVK\",
        \"terminal_language_code\": \"EN\",
        \"terminal_serial_number\": \"325-320-924\",
        \"terminalid_acquirer\": \"66000001\",
        \"currency\": \"EUR\",
        \"username\": \"testuser\",
        \"password\": \"testpassword\",
        \"user_email\": \"[email protected]\",
        \"user_phone_number\": \"+421910876567\"
        }"

Request Parameters

ParameterTypeRequiredDescription
packageorderuuidstringrequiredIdentifier of registered merchant in TECS system, provided in the response of the registerNewMerchant call
productidstringoptionalOptional identifier of the product in TECS Platform; if it's not specified, a default product is used as specified in package definition
terminal_locationstringrequiredTerminal location
terminal_country_codestring (3AN)requiredTerminal country code; must be in "ISO-3166 ALPHA-3" format
terminal_language_codestring (2AN)requiredTerminal language code; must be in "ISO 639-1" format
terminal_serial_numberstring (50AN)optionalTerminal serial number
terminalid_acquirerstringoptionalTerminal ID provided by the acquirer
currencystring (3AN)requiredTransaction currency; must be in "ISO 4217" format
usernamestringoptionalMerchant username for MPOS; if it's not provided, it will be generated by TECS and provided as a response parameter
passwordstringoptionalMerchant password for MPOS; if it's not provided, it will be generated by TECS and provided as a response parameter
user_emailstringoptionalEmail address of the user acting on behalf of the merchant
user_phone_numberstringoptionalPhone number of the user acting on behalf of the merchant; Must be in international format: '+' country code phone number

Example: +421910711234

Example Response

{
    "response_code": "0",
    "response_text": "OK",
    "terminalid": "88091105",
    "username": "testuser",
    "password": "testpassword"
}

Response Parameters

ParameterTypeDescription
responseCodeintResponse code (0 = OK, otherwise an error code)
responseMessagestringHuman readable error description
terminalidnumericThe terminal identification code given by TECS Platform
usernamestringTECS-generated merchant username if not provided in the request
passwordstringTECS-generated merchant password if not provided in request

Error Codes

Error CodeError Message
24000You don't have permissions (state User_HasNotRole)
24001You don't have permissions (state Mandator_IsNotTheSame)
24012Mandatory fields are not filled %1$s (state MandatoryFields_AreNotFilled)
24014with arbitrary message (state Unexpected_Exception)
24021packageid (must be present, in correct format)
24022terminal_location (must be present, in correct format)
24023terminal_country_code (must be present, in correct format)
24024terminal_language_code (must be present, in correct format)
24025terminal_serial_number (must be present, in correct format)
24026currency (must be present, in correct format)
24034user_email (incorrect email address format)
24035user_phone_number (incorrect phone number format)
25000INTERNAL_SERVER_ERROR
25001OAUTH_INTERACTION_FAILED
25002OAUTH_INVALID_TOKEN
25003UNAUTHORIZED
25004BAD_REQUEST
25005USER_INACTIVE
25006CORPORATE_ACCOUNT_ERROR
25007TECS_TERM_NOT_FOUND
25008MANDATOR_NOT_FOUND
25009INVALID_TEMPLATE
25010INVALID_COUNTRY
25011TECS_COMPANY_NOT_FOUND
25012DATA_INTEGRITY_ERROR
25013DATA_ACCESS_ERROR
26030PIN_REQUIREMENT_FAILED
26031PIN_ALREADY_EXISTS
26032CONSUMER_NOT_PREREGISTERED_STATUS
26033CONSUMER_EXISTS
26034WRONG_PHONE_FORMAT
26097General_ERROR
26098INVALID_INPUT
26099INVALID_CREDENTIALS
27000INVALID_INPUT
27002INVALID_PERMISSION
27005BUSINESSREGNO_HAS_TO_BE_UNIQUE
27006TID_HAS_TO_BE_UNIQUE
27007WRONG_TID_FORMAT
27008WRONG_PHONE_FORMAT
27010WRONG_EMAIL_FORMAT

Register An Acquirer

The registerAdditionalAcquiring call can be used to register an acquirer to a terminal

Example Request

curl -X POST \
    "https://dev.tecs.at/merchantportalws/registerAdditionalAcquiring" \
    -u User1:Password1 \
    -H "accept: */*" \
    -H "Content-Type: application/json" \
    -d "{ \"additionalData\": {\"firstname\": \"John\",\"surname\": \"Doe\",\"type\": \"tx-300\",\"version\": \"v1.2.3\"},
           \"currency\": \"EUR\",
           \"packageOrderUUID\": \"16acb5a4-e573-423c-a024-fae90ea45d70\",
           \"productIdAcquirer\": \"874d84a8-a6f4-47fa-b594-944593fc394b\",
           \"terminalIdAcquirer\": 66000001,
           \"terminalIds\": [ 77000001, 77000002, 77000003 ],
           \"vuNummer\": \"VU-20230501-00123\"
           }"

Request Parameters

ParameterTypeRequiredDescription
additionalDataarrayoptionalAdditional data to provide to the acquirer; Format: {parameter: value,….;}.
currencystring (3AN)requiredTransaction currency; must be in "ISO 4217" format
packageorderuuidstringrequiredIdentifier of registered merchant in TECS Platform, provided by TECS in "Merchant and terminal registration" call
productIdAcquirerstringrequiredIdentifier of acquiring product in TECS namespace
terminalid_acquirerstringoptionalTerminal ID provided by the acquirer
terminalIdsstringoptionalList of terminals IDs to be assigned to the acquirer. If not provided, acquiring will be activated for all terminals registered with the merchant.
vu-nummerstring(15AN)requiredMerchant contract number with the acquirer

Example Response

{
    "response_code": "0",
    "response_text": "OK"
}

Response Parameters

ParameterTypeDescription
responseCodeintResponse code (0 = OK, otherwise an error code)
responseMessagestringHuman readable error description

Error Codes

Error CodeError Message
24000You don't have permissions (state User_HasNotRole)
24001You don't have permissions (state Mandator_IsNotTheSame)
24012Mandatory fields are not filled %1$s (state MandatoryFields_AreNotFilled)
24014with arbitrary message (state Unexpected_Exception)
24026currency (must be present, in correct format)
24027vu_nummer (must be present, in correct format)
24028packageorderuuid (must be present, in correct format)
25000INTERNAL_SERVER_ERROR
25001OAUTH_INTERACTION_FAILED
25002OAUTH_INVALID_TOKEN
25003UNAUTHORIZED
25004BAD_REQUEST
25005USER_INACTIVE
25006CORPORATE_ACCOUNT_ERROR
25007TECS_TERM_NOT_FOUND
25008MANDATOR_NOT_FOUND
25009INVALID_TEMPLATE
25010INVALID_COUNTRY
25011TECS_COMPANY_NOT_FOUND
25012DATA_INTEGRITY_ERROR
25013DATA_ACCESS_ERROR
26030PIN_REQUIREMENT_FAILED
26031PIN_ALREADY_EXISTS
26032CONSUMER_NOT_PREREGISTERED_STATUS
26033CONSUMER_EXISTS
26034WRONG_PHONE_FORMAT
26097General_ERROR
26098INVALID_INPUT
26099INVALID_CREDENTIALS

Deactivate a Terminal

See an example of the deactivateTerminal request and response below:

Example Request

curl -X POST \
    "https://test.tecs.at/merchantportalws/deactivateTerminal" \
    -u User1:Password1 \
    -H "accept: application/json" \
    -H "content-type: application/json" \
    -d "{ \"terminalid\": \"88091105\",
        \"reason_deactivation\": \"Terminal was stolen\"
        }"

Request Parameters

ParameterTypeRequiredDescription
terminalidnumericrequiredThe terminal identification code generated by TECS Platform
reason_deactivationstringrequiredThe reason the terminal is being deactivated

Example Response

{
    "response_code": "0",
    "response_text": "OK",
}

Response Parameters

ParameterTypeDescription
responseCodeintResponse code (0 = OK, otherwise an error code)
responseMessagestringHuman readable error description

Error Codes

Error CodeError Message
24000You don't have permissions (state User_HasNotRole)
24001You don't have permissions (state Mandator_IsNotTheSame)
24012Mandatory fields are not filled %1$s (state MandatoryFields_AreNotFilled)
24014with arbitrary message (state Unexpected_Exception)
24029terminalid (must be present, in correct format)
24030reason_deactivation (must be present, in correct format)
25000INTERNAL_SERVER_ERROR
25001OAUTH_INTERACTION_FAILED
25002OAUTH_INVALID_TOKEN
25003UNAUTHORIZED
25004BAD_REQUEST
25005USER_INACTIVE
25007TECS_TERM_NOT_FOUND
25008MANDATOR_NOT_FOUND
25012DATA_INTEGRITY_ERROR
25013DATA_ACCESS_ERROR

Updated 5 months ago