Terminal Management

Guides for creating and managing terminals via the REST API.

Creating a Terminal

Endpoint

POST /api/v1/terminal/create

The request body contains a JSON model with the table fields necessary to create a terminal.

Note on Terminal vs. POS User

This endpoint is for creating new Terminal IDs (TIDs) for transaction processing. To create a new POS user account, please see the Creating an Agent (POS User) section.

Note on Terminal Groups

For each merchant, 3 groups of terminals are automatically created: "DEFAULT" for mPOS, "SOFTPOS" for SoftPOS, and "SBP" for SBP. You must specify the group name in the TerminalGroupCode field. If not specified, the terminal is created in the "DEFAULT" group.

Terminal Request Body

Field Name	Type	Mandatory	Description
`BranchID`	Integer	Yes	Merchant/Branch ID
`Name`	String	Yes	Terminal name (TID)
`Alias`	String	Yes	Terminal alias (TID)
`SIC`	String	Yes	MCC for the terminal
`Title`	String	Yes	Terminal title (TID)
`Currency`	String	Yes	Currency code (numeric ISO 4217)
`Country`	String	Yes	Country code (ISO 3166-1 numeric)
`City`	String	Yes	City
`Location`	String	Yes	Location (Latin characters)
`EntryCaps`	String	Yes	Terminal capabilities code
`RegionCode`	String	Yes	Region code
`CountryCode`	String	Yes	Country code (ISO 3166-1 alpha-2)
`DeviceInfo`	JsonObject	Yes	Device object
`TerminalGroupID`	Integer	No	Terminal Group ID
`TerminalGroupCode`	String	No	Name of the terminal group
`Phone`	String	No	Terminal holder phone number
`State`	Integer	No	Status (0 - blocked, 1 - active)
`Description`	String	No	Terminal description
`Class`	String	No	Terminal class
`BackRetailerID`	String	No	Merchant identifier (MID)
`Owner`	String	No	Terminal owner
`Region`	String	No	Region name
`Branch`	String	No	Merchant/branch name
`ZIP`	String	No	Postal code
`TimeOffset`	String	No	Time zone
`ContactlessCapable`	String	No	Contactless capability
`SelfSevice`	String	No	Self Service capability
`Type`	String	No	Terminal type
`Latitude`	Number	No	Latitude
`Longitude`	Number	No	Longitude
`WithAccounts`	Boolean	No	Link to accounts
`ForAccount`	Boolean	No	For a specific account
`CurrentAccountID`	Integer	No	ID of the user making the request
`Sbp`	JsonObject	No	SBP Settings
`IP`	String	No	Request IP address
`Lang`	String	No	Language

Value Dictionaries

SIC – MCC codes are indicated in the international format (e.g. "5411")
RegionCode – The codes of the regions of South Africa are indicated (e.g., “GP” for Gauteng)
Currency – The country currency code is indicated in the numeric ISO 4217 format (710 for ZAR)
Country – The country code is indicated in the ISO 3166-1 numeric format (710 for South Africa)

EntryCaps

Type	Description
`0`	Unknown
`1`	No TerminalUsed
`2`	Magnetic Stripe Reader
`3`	Bar code
`4`	OCR
`5`	Magnetic stripe and chip reader – Use it
`6`	Key Entry
`7`	Magnetic stripe reader and key entry
`8`	Magnetic stripe and chip and key entry
`9`	Chip reader
`10`	None

Example: Create Terminal Request

{
  "BranchID": 18349,
  "Name": "04202298",
  "SIC": "5411",
  "Title": "04202298",
  "Currency": "710",
  "Country": "710",
  "City": "Johannesburg",
  "Location": "South Africa",
  "TerminalGroupCode": "DEFAULT",
  "EntryCaps": "5",
  "RegionCode": "GP",
  "CountryCode": "ZA",
  "DeviceInfo": {
    "PhoneManufacturer": "Generic",
    "PhoneModel": "Windows_RestAPI",
    "DeviceID": "",
    "DeviceType": "1",
    "AppFramework": "java",
    "OS": "Windows",
    "OSVersion": "10",
    "AppID": "RestAPI",
    "BuildNumber": "2.4.390248"
  },
  "GMT": 2,
  "AppFramework": "java",
  "Lang": "en",
  "IP": "102.132.95.88"
}

Terminal Response Body

Field Name	Type	Description
`Terminal`	Object	Terminal object
`ID`	Integer	Terminal identifier
`Alias`	String	Terminal alias
`Name`	String	Terminal name
`FinstID`	Integer	Financial institution identifier
`ClientID`	Integer	Merchant ID
`BranchID`	Integer	Branch ID
`BranchName`	String	Branch name
`SIC`	String	MCC for the terminal
`Location`	String	Location
`Class`	String	Terminal class
`Title`	String	Terminal title
`Description`	String	Terminal description
`BackRetailerID`	String	MID Merchant identifier
`Currency`	String	Currency code
`Country`	String	Country
`Owner`	String	Terminal owner
`Region`	String	Region name
`Branch`	String	Merchant/branch name
`City`	String	City
`ZIP`	String	Postal code
`Phone`	String	Terminal holder phone number
`TimeOffset`	String	Time zone
`EntryCaps`	String	Terminal capabilities
`Latitude`	Number	Latitude
`Longitude`	Number	Longitude
`ContactlessCapable`	String	Contactless capability
`SelfSevice`	String	Self Service capability
`Type`	String	Terminal type
`RegionCode`	String	Region code
`State`	Integer	Status (0 - blocked, 1 - active)
`GroupID`	Integer	Terminal Group ID
`Sbp`	JsonObject	SBP Settings
`ErrorCode`	String	Execution result code
`ErrorMessage`	String	Execution result message

Example: Create Terminal Response

{
  "Terminal": {
    "ID": 8272,
    "Alias": null,
    "Name": "04202298",
    "FinstID": 3012,
    "ClientID": 18349,
    "BranchID": 18349,
    "BranchName": null,
    "Selected": false,
    "PosCount": null,
    "SIC": "5411",
    "Location": "South Africa",
    "Class": "",
    "Title": "04202298",
    "Description": null,
    "BackRetailerId": null,
    "Currency": "710",
    "Country": "710",
    "Owner": null,
    "Region": null,
    "Branch": null,
    "City": "Johannesburg",
    "ZIP": null,
    "Phone": null,
    "TimeOffset": null,
    "EntryCaps": "5",
    "Latitude": null,
    "Longitude": null,
    "ContactlessCapable": "1",
    "SelfService": null,
    "Type": "",
    "RegionCode": "GP",
    "Accounts": null,
    "SettleStatus": 0,
    "Settled": null,
    "SettleTry": null,
    "CanStartSettlement": false,
    "TMK": null,
    "TMKKCV": null,
    "VN_OCEAN_TID": null,
    "VN_OCEAN_PSW": null,
    "CanExport": true,
    "ProccessTry": null,
    "ProcessStatus": 0,
    "ProcessCreateSuccess": false,
    "DirectPosCount": null,
    "State": 1,
    "GroupID": 2541,
    "IsCarousel": false
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}