Device - MineSec Developer Docs

⚠️

Legacy API — deprecated. This page documents the legacy /api/v2 Device endpoints, kept for existing integrations. New integrations should use the current Device API. Once your PBO group has been switched over to the current Service API, every endpoint on this page — including reads — returns code: 13310 ("Your group has open the multi_acquirers;please use the new Service API") instead of working. See the Service API overview for details.

The one exception is Send Activation Code (POST /api/v2/device/code), which keeps working before and after the switch. Update Activation Code has no equivalent in the current API — see the note on that section before moving off it.

Terminal List

Retrieves a list of terminal devices associated with a merchant.

Get Terminal List

GET /api/v2/device
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	query	string	true	Merchant ID

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response List<T>` Data: Device

Example Response (200)

Example Response - Terminal List

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "total": 10,
    "current": 1,
    "hasNext": false,
    "records": [
      {
        "deviceType": "COTS",
        "appVersion": "1.2.3",
        "deviceAdmin": "admin",
        "extParams": {
          "subMid": "000",
          "clientId": "000",
          "jwtSecret": "000",
          "acqMid": "000",
          "subTid": "000",
          "mid": "000",
          "acqTid": "000"
        },
        "deviceId": "CD-12345678",
        "activateCodeAlias": "Terminal-01",
        "uuid": "abcd-1234-efgh-5678",
        "deviceStatus": 1,
        "activesAt": "2023-01-01T10:00:00Z",
        "createdAt": "2022-12-25T08:00:00Z",
        "emvParams": "{\"amexFloorLimit\":\"00000100\",\"terminalCountryCode\":\"0840\",\"txnCurrencyCode\":\"0840\",\"terminalType\":\"21\",\"terminalCapability\":\"0068C8\",\"emvFlags\":\"VMAUJDP\"}",
        "methodList": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}",
        "updatedAt": "2023-02-15T14:30:00Z",
        "serverUrl": "https://api.example.com",
        "customerId": "C-123456",
        "licenseId": "L-123456",
        "signKeyId": "KEY-123456",
        "cardBdkId": "BDK-123456",
        "profileId": "P-123456",
        "isDevice": true
      }
    ]
  }
}

Response Field Notes

The linked Device schema only covers the request-shaped fields; the actual list/detail response includes several more fields worth explaining:

Field	Meaning
`deviceId`	The device's unique ID. While unactivated it carries a `CD-` prefix (e.g. `CD-12345678`) and identifies an activation code; once activated, the same field identifies the physical device. Other endpoints on this page refer to this same value as `sdkId` (path parameter naming is inconsistent across this legacy API — they are not different IDs).
`deviceStatus`	Numeric lifecycle status: `0` = Inactive (activation code not yet claimed), `1` = Active, `2` = Logout, `3` = Decommission.
`isDevice`	`true` once the record represents an activated device rather than a still-pending activation code (i.e. `deviceId` no longer starts with `CD-`).
`uuid`	The merchant ID (`mchId`) this device/code belongs to — not a device-level identifier despite the generic name.
`deviceAdmin`	The device's admin/passcode, base64-decoded for display.

Terminal Detail

Retrieves a single terminal device or activation code by ID.

Get Terminal Detail

GET /api/v2/device/{sdkId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
sdkId	path	string	true	Device ID (same value as `deviceId` in the Terminal List response — see the field notes above)

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: Device (plus `mchName`, `groupName`)

Example Response (200)

Example Response - Terminal Detail

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "deviceType": "COTS",
    "appVersion": "1.2.3",
    "deviceAdmin": "admin",
    "extParams": {
      "acqMid": "1234567850001",
      "acqTid": "0001252001"
    },
    "deviceId": "9F3A7B21C450",
    "activateCodeAlias": "Terminal-01",
    "uuid": "abcd-1234-efgh-5678",
    "deviceStatus": 1,
    "activesAt": "2023-01-01T10:00:00Z",
    "createdAt": "2022-12-25T08:00:00Z",
    "emvParams": "{\"amexFloorLimit\":\"00000100\",\"terminalCountryCode\":\"0840\",\"txnCurrencyCode\":\"0840\",\"terminalType\":\"21\",\"terminalCapability\":\"0068C8\",\"emvFlags\":\"VMAUJDP\"}",
    "methodList": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}",
    "updatedAt": "2023-02-15T14:30:00Z",
    "mchName": "Coffee Shop Downtown",
    "groupName": "Acme Merchant Services",
    "isDevice": true
  }
}

If the device doesn't exist or belongs to a different group, the call fails with code: 10000 ("Parameters Error (not exist)") — still a 200 at the HTTP level, not a 404.

Generate Activation Code

Creates a new activation code for a terminal device.

Generate Activation Code

POST /api/v2/device
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
activateCodeAlias	body	string	true	A friendly name for the activation code
deviceType	body	string	true	Device type (e.g., "COTS")
mchId	body	string	true	Merchant ID
emvParams	body	object	false	EMV configuration parameters
methodList	body	string	false	Supported payment methods
extParams	body	string	false	Additional parameters

Request Body Example

Example Request - Generate Activation Code

{
  "emvParams": {
    "amexFloorLimit": "00000100",
    "terminalCountryCode": "0840",
    "txnCurrencyCode": "0840",
    "amexExReaderCapability": 18000,
    "amexReaderCapability": "C3",
    "terminalType": 21,
    "terminalCapability": "0068C8",
    "emvFlags": "VMAUJDP"
  },
  "activateCodeAlias": "Store-Terminal-01",
  "deviceType": "COTS",
  "methodList": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}",
  "extParams": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}",
  "mchId": "M-12345678"
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Generate Activation Code

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": "CD-87654321",
    "activationCode": "87654321"
  }
}

Update Activation Code

⚠️

No equivalent in the current API. PUT /api/v2/device/code/{codeId} has no counterpart under /api/openapi/v1/device. If you edit an activation code's alias/EMV/method-list/ext params before it's claimed by a device, check with the platform team for a migration path before your PBO group is switched over.

Updates an activation code that hasn't been claimed by a device yet. Scoped to the activation code rather than an activated device — the body shape is similar to Update Terminal, except activateCodeAlias is required here (it's optional on Update Terminal).

Update Activation Code

PUT /api/v2/device/code/{codeId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
codeId	path	string	true	The activation code, without the `CD-` prefix (e.g. `87654321`)
activateCodeAlias	body	string	true	A friendly name for the activation code
deviceType	body	string	false	Device type
deviceAdmin	body	string	false	Admin password
emvParams	body	string	false	EMV configuration parameters
methodList	body	string	false	Supported payment methods
extParams	body	string	false	Additional parameters

Request Body Example

Example Request - Update Activation Code

{
  "activateCodeAlias": "Store-Terminal-03",
  "deviceType": "COTS",
  "deviceAdmin": "123456",
  "methodList": "{\"all\":{\"tid\":\"71001008\",\"mid\":\"001007514956668\"}}",
  "extParams": "{\"all\":{\"tid\":\"71001008\",\"mid\":\"001007514956668\"}}"
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Update Activation Code

{
  "msg": "SUCCESS",
  "code": 0
}

Terminal Logout & Suspend

Updates the status of a terminal device (logout, decommission, etc.).

Terminal Logout & Suspend

DELETE /api/v2/device/{deviceId}
Authorization: Bearer {jwt}

Parameters

Scenario1:

Name	In	Type	Required	Description
deviceId	path	string	true	activation code with 'CD-' prefix, unbind and delete the activation code

Scenario2:

Name	In	Type	Required	Description
deviceId	path	string	true	Device ID (same value as `sdkId` elsewhere on this page — see the field notes above)
deviceStatus	query	integer	false	2-Logout; 3-Decommission

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Terminal Logout

{
  "msg": "SUCCESS",
  "code": 0
}

Update Terminal

Updates an existing terminal device configuration.

Update Terminal

PUT /api/v2/device/{deviceId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
deviceId	path	string	true	Device ID
deviceType	body	string	false	Device type
deviceAdmin	body	string	false	Admin password
activateCodeAlias	body	string	false	A friendly name for the terminal
emvParams	body	string	false	EMV configuration parameters
methodList	body	string	false	Supported payment methods
extParams	body	string	false	Additional parameters

Request Body Example

Example Request - Update Terminal

{
  "deviceType": "COTS",
  "deviceAdmin": "123456",
  "activateCodeAlias": "Store-Terminal-02",
  "emvParams": "{\"amexFloorLimit\":\"00000100\",\"terminalCountryCode\":\"0840\",\"txnCurrencyCode\":\"0840\",\"amexExReaderCapability\":\"18E00003\",\"amexReaderCapability\":\"C3\",\"terminalType\":\"21\",\"terminalCapability\":\"0068C8\",\"emvFlags\":\"VMAUJDP\"}",
  "methodList": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}",
  "extParams": "{\"all\":{\"tid\":\"71001007\",\"mid\":\"001007514956667\"}}"
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Update Terminal

{
  "msg": "SUCCESS",
  "code": 0
}

Idle Terminal

Marks an activation code as idle without deleting it, freeing it for re-activation. If the code was already linked to an activated device, that device is logged out as part of the same operation.

Idle Terminal

DELETE /api/v2/device/{code}/idle
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
code	path	string	true	Activation code, without the `CD-` prefix (e.g. `87654321`)

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Idle Terminal

{
  "msg": "SUCCESS",
  "code": 0
}

Send Activation Code

Emails an existing activation code to the given address.

Unlike the other endpoints on this page, this one does not return 13310 — it keeps working the same way before and after your PBO group is switched over.

Send Activation Code

POST /api/v2/device/code
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
sdkId	body	string	true	Device ID / activation code to send
email	body	string	true	Destination email address

Request Body Example

Example Request - Send Activation Code

{
  "sdkId": "87654321",
  "email": "[email protected]"
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`

Example Response (200)

Example Response - Send Activation Code

{
  "msg": "SUCCESS",
  "code": 0
}

Get Device EMV Params

Returns the resolved EMV parameters and AID list currently pushed to a device.

Get Device EMV Params

GET /api/v2/device/emv/{sdkId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
sdkId	path	string	true	Device ID

Example Response (200)

Example Response - Get Device EMV Params

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "emvParams": {
      "amexFloorLimit": "00000100",
      "terminalCountryCode": "0840",
      "txnCurrencyCode": "0840",
      "terminalType": 21,
      "terminalCapability": "0068C8",
      "emvFlags": "VMAUJDP"
    },
    "emvAID": [
      {
        "id": 1675,
        "aid": "A0000000041010",
        "emvName": "l3-mastercard",
        "emvVersion": "v1",
        "paymentMethod": "02"
      },
      {
        "id": 1680,
        "aid": "A0000000031010",
        "emvName": "l3-visa",
        "emvVersion": "v1",
        "paymentMethod": "01"
      }
    ]
  }
}

Merchant Transaction