Agent / POS User Management

A POS User (Agent) account is required to process transactions on a payment terminal. Agents are assigned to specific Terminals (Terminal IDs).

Creating an Agent (POS User)

Endpoint

POST /api/v1/merchant/{merchantId}/pos/create

Replace {merchantId} with your Cycle MerchantID, or the ID of the merchant for whom you are creating the agent.

Agent Request Body

Field Name	Type	Mandatory	Description
`Name`	String	Yes	Agent's name
`Email`	String	Yes	Email of the agent
`Phone`	String	Yes	Phone (e.g., +27821234567)
`BranchID`	Integer	Yes	Branch ID (if no branch, use Client ID)
`ClientID`	Integer	Yes	Merchant ID
`TerminalID`	Integer	No	Internal terminal identifier
`TID`	String	No	Terminal name from the client's set
`State`	Integer	No	Status (0 - blocked, 1 - active)
`Password`	String	No	Password
`SecretKey`	String	No	Secret key
`AddressDeFacto`	String	No	Actual address
`SendWelcomeEmail`	Boolean	No	Send a welcome invitation
`BranchesActions`	Array	No	Array of branches and rights to assign
`AccountType`	Integer	No	Account type
`ImageAvatar`	JsonObject	No	Agent logo
`MobileSettings`	JsonObject	No	Mobile settings
`PrinterSettings`	JsonObject	No	Printer settings
`PrinterAndTaxSettings`	JsonObject	No	Printer and tax settings
`CurrentAccountID`	Integer	No	ID of the user making the request

Example: Create Agent Request

{
  "Name": "Cycle Demo Agent",
  "Email": "agent@cycledemo.co.za",
  "Phone": "+27829876543",
  "ClientID": 26991,
  "BranchID": 26991,
  "TID": "CYCLE-POS-01",
  "State": 1,
  "Password": "password123",
  "SecretKey": "secretkey123",
  "AddressDeFacto": "456 Sample Ave, Pretoria, 0002",
  "SendWelcomeEmail": true,
  "BranchesActions": [
    {
      "BranchID": 26991,
      "Actions": [220]
    }
  ],
  "AccountType": 11,
  "MobileSettings": {
    "Features": {
      "AcceptCards": true,
      "AcceptCash": true,
      "AcceptPrepaid": true,
      "AcceptCredit": true,
      "AcceptOuterCard": true,
      "ShowInventory": true,
      "RegularPayments": true,
      "Offline": true,
      "AsyncCashProcessing": true,
      "InternalUpdate": true,
      "AutoLogin": true,
      "Inherited": true,
      "ChangeClientLogo": true
    },
    "MobHomeURL": "https://cycledemo.co.za/home",
    "MobHomeURLNull": false,
    "MobQRUrlNull": true,
    "AllowLinkedCards": 1,
    "BoxplatPayDashboard": false,
    "BoxplatPayDashboardNull": true,
    "AllowCreditVoucherReverses": 0,
    "MobileAppPasswordStore": true,
    "BarcodeScanner": true,
    "BarcodeScannerNull": true
  },
  "CurrentAccountID": 21041,
  "Location": {
    "Latitude": -25.7479,
    "Longitude": 28.2293
  },
  "Country": "South Africa",
  "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"
}

Agent Response Body

Field Name	Type	Description
`POS`	Object	Agent information object
`ID`	Integer	Identifier
`State`	Integer	Status (active/blocked)
`Name`	String	Agent's name
`Email`	String	Email of the agent
`Phone`	String	Phone number
`AvatarUrl`	String	Link to avatar
`HasAvatar`	Boolean	Indicates if avatar exists
`IsAdministrator`	Boolean	Is a client administrator
`IsSystemUser`	Boolean	Is a system user
`Deleted`	Boolean	Indicates if deleted
`CountryID`	String	Country ID
`FInstID`	Integer	Financial institution identifier
`ClientID`	Integer	Merchant ID
`MobileSettings`	Object	Mobile settings
`PrinterAndTaxSettings`	Object	Printer settings
`ErrorCode`	Integer	Execution result code
`ErrorMessage`	String	Execution result message
`Validations`	Array	Validation results

Example: Create Agent Response

{
  "Pos": {
    "ID": 27014,
    "State": 1,
    "AccountTypeID": 11,
    "Name": "Cycle Demo Agent",
    "Email": "agent@cycledemo.co.za",
    "Phone": "+27(82)987-65-43",
    "AvatarUrl": null,
    "HasAvatar": false,
    "IsAdministrator": false,
    "IsSystemUser": false,
    "Deleted": false,
    "CountryID": "ZA",
    "CurrencyID": "ZAR",
    "FInstID": 3012,
    "ClientID": 26991,
    "MobileSettings": {
      "Features": {
        "AcceptCards": true,
        "AcceptCash": true,
        "AcceptPrepaid": true,
        "AcceptCredit": true,
        "AcceptOuterCard": true,
        "ShowInventory": true,
        "RegularPayments": true,
        "Offline": true,
        "AsyncCashProcessing": true,
        "InternalUpdate": true,
        "AutoLogin": true,
        "Inherited": true,
        "ChangeClientLogo": true
      },
      "MobQRUrl": null,
      "MobHomeURL": "https://cycledemo.co.za/home",
      "MobQRUrlEffective": null,
      "MobHomeURLEffective": "https://cycledemo.co.za/home",
      "AllowLinkedCards": 1,
      "AllowLinkedCardsEffective": 1,
      "BoxplatPayDashboard": false,
      "BoxplatPayDashboardEffective": false,
      "AllowCreditVoucherReverses": 0,
      "AllowCreditVoucherReversesEffective": 0,
      "MobileAppPasswordStore": true,
      "BarcodeScanner": true,
      "BarcodeScannerEffective": true
    },
    "PrinterAndTaxSettings": {
      "PrinterID": null,
      "PrinterIDEffective": null,
      "PrinterCode": null,
      "PrinterCodeEffective": null
    }
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}

Editing an Agent

Endpoint

POST /api/v1/merchant/{merchantId}/pos/{posId}/update

Replace {merchantId} and {posId} with the relevant IDs.

Edit Agent Request Body

Field Name	Type	Description
`Name`	String	Agent's name
`Email`	String	Email of the agent
`Phone`	String	Phone number
`TerminalID`	Integer	Terminal identifier
`TID`	String	External terminal ID
`State`	Integer	Status (0 - blocked, 1 - active)
`Password`	String	Password
`AddressDeFacto`	String	Actual address
`CountryID`	String	Country ID
`CurrencyID`	String	Currency ID
`LanguageID`	String	Language
`Unlock`	Boolean	Reset login attempts and unblock
`SecretKey`	String	Secret key
`TaxID`	String	Agent TIN
`UserKindID`	Integer	User Type Identifier
`Image`	JsonObject	Image object
`MobileSettings`	JsonObject	Mobile settings
`ServerFiscalization`	JsonObject	Server fiscalization settings
`PrinterAndTaxSettings`	JsonObject	Printer and tax settings
`PrinterSettings`	JsonObject	Printer settings
`AcquirersSettings`	JsonObject	Acquiring settings
`CurrentAccountID`	Integer	ID of user making request

Example: Edit Agent Request

{
  "ID": "10331",
  "Name": "Demo User 2.0",
  "Email": "user2@cycledemo.co.za",
  "Phone": "+27821112222",
  "Unlock": true,
  "SecretKey": "123123123",
  "MobileSettings": {
    "Features": {
      "AcceptCards": true,
      "AcceptCash": true,
      "AcceptPrepaid": true,
      "AcceptCredit": true,
      "AcceptOuterCard": true,
      "ShowInventory": true,
      "RegularPayments": true,
      "Offline": true,
      "AsyncCashProcessing": true,
      "InternalUpdate": true,
      "AutoLogin": true,
      "Inherited": true,
      "BarcodeScanner": true
    }
  },
  "Location": {
    "Latitude": -26.2041,
    "Longitude": 28.0473
  },
  "Country": "South Africa",
  "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"
}

Edit Agent Response Body

Field Name	Type	Description
`POS`	Object	Agent information object
`ID`	Integer	Identifier
`State`	Integer	Status (active/blocked)
`Name`	String	Agent's name
`Email`	String	Email of the agent
`Phone`	String	Phone number
`AvatarUrl`	String	Link to avatar
`HasAvatar`	Boolean	Indicates if avatar exists
`IsAdministrator`	Boolean	Is a client administrator
`IsSystemUser`	Boolean	Is a system user
`Deleted`	Boolean	Indicates if deleted
`CountryID`	String	Country ID
`FInstID`	Integer	Financial institution identifier
`ClientID`	Integer	Merchant ID
`MobileSettings`	Object	Mobile settings
`PrinterAndTaxSettings`	Object	Printer settings
`ErrorCode`	Integer	Execution result code
`ErrorMessage`	String	Execution result message
`Validations`	Array	Validation results

Example: Edit Agent Response

{
  "Pos": {
    "ID": 10331,
    "FInstID": 3012,
    "ClientID": 10320,
    "State": 1,
    "AccountTypeID": 20,
    "Name": "Demo User 2.0",
    "Email": "user2@cycledemo.co.za",
    "Phone": "+27(82)111-2222",
    "AvatarUrl": "/i/x.png",
    "IsAdministrator": false,
    "IsSystemUser": false,
    "HasAvatar": false,
    "Deleted": false,
    "CurrencyID": "ZAR",
    "CountryID": "ZA"
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}

Batch Editing Agents / POS Users

Endpoint

POST /api/v1/merchant/{merchantId}/pos/updatebulk

This endpoint allows you to update multiple agents in a single request. The request body contains an array of agents to modify. If an incorrect agent or printer is specified, settings will be applied only to the valid agents, and errors for the invalid ones will be returned in the `Validations` array.

Batch Edit Request Body

Field Name	Type	Description
`PosBulk`	Array	Array of agent objects to update
`Email`	String	Agent's email to identify the user
`State`	Integer	Agent status (0=blocked, 1=active)
`PrinterAndTaxSettings`	JsonObject	Printer settings
`PrinterID`	Integer	Printer ID
`PrinterCode`	String	Printer code

Example: Batch Edit Request

{
  "PosBulk": [
    {
      "Email": "agent1@cycledemo.co.za",
      "State": 1,
      "PrinterAndTaxSettings": {
        "PrinterID": 22,
        "PrinterCode": "CYCLE-POS-P1"
      }
    },
    {
      "Email": "agent2@cycledemo.co.za",
      "State": 0,
      "PrinterAndTaxSettings": {
        "PrinterID": 25,
        "PrinterCode": "CYCLE-NULL"
      }
    },
    {
      "Email": "nonexistent@email.demo",
      "State": 0,
      "PrinterAndTaxSettings": {
        "PrinterID": 99,
        "PrinterCode": "INVALID-PRINTER"
      }
    }
  ],
  "Location": {
    "Latitude": -26.2041,
    "Longitude": 28.0473
  },
  "Country": "South Africa",
  "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"
}

Example: Batch Edit Response

{
  "Pos": null,
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": [
    {
      "Type": 1,
      "Property": "nonexistent@email.demo",
      "Code": 563,
      "Message": "Account not found"
    }
  ]
}

Getting Information about an Agent

Get by ID

GET /api/v1/merchant/{merchantId}/pos/{posId}

Example Request: https://web-api-pro-demo.cardport.net/api/v1/merchant/18349/pos/18351

Response Body (Get by ID)

Field Name	Type	Description
`Pos`	JsonObject	Agent object
`ID`	Integer	Agent ID
`State`	Integer	Status (1: Active, 0: Blocked)
`AccountTypeID`	Integer	Account type ID
`Name`	String	Agent name
`Email`	String	Agent email
`Phone`	String	Agent phone
`SecretKey`	String	Agent secret key
`Logon`	JsonObject	Logon details
`MobileSettings`	JsonObject	Mobile application settings
`PrinterAndTaxSettings`	JsonObject	Printer and tax settings
`ErrorCode`	Integer	Error code
`ErrorMessage`	String	Error message
`Validations`	Array	Validation errors

Get by Parameters

POST /api/v1/merchant/{merchantId}/pos/list

This method can be used to get an Agent ID by login, retrieve passwords and secret keys, or search for all agents matching specific parameters.

Merchants

Terminals