Devices

A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.

Fetch a Device

Retrieve the details of an existing Device.

To check the connectivity of the device, include ?include_connection\=true\ at the end of the request endpoint.

Request
path Parameters
device_id
required
string

ID of the Device.

query Parameters
include_connection
boolean

Specifies whether the connection information should be included.

Responses
200

Single Device object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object or null

Information used to configure how the Device handles transactions.

connection
string

Details if the Device is connected and online. Only returned when include_connection parameter provided.

created_at
string <date-time>

Timestamp of when the object was created.

description
string or null

Additional information about device (e.g. self serving terminal).

enabled
boolean

Details if the Device resource is enabled. Set to false to disable the Device.

id
string

The ID of the activated Device.

idle_message
string or null

The message that diplays on the device after a period of inactivity.

merchant
string

ID of the Merchant resource.

model
string

Details the model of the card reader.

name
string

Name of the Device.

serial_number
string or null

Serial number of the device.

object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/devices/{device_id}
Request samples
curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/vnd.json+api" \
  -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
Response samples
application/hal+json
{}

Initiate Action on Device

Initiate an action on a Device. These actions include activation, rebooting, setting an idle message, or deactivate it.

Request
path Parameters
device_id
required
string

ID of the Device.

Request Body schema: application/hal+json
Any of:
action
required
string

The action you want to perform on the device. Use ACTIVATE to activate a the physical model with the device resource.

Value: "ACTIVATE"
activation_code
string

Used when action is ACTIVATE. Provide the input code that shows up on the device screen.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
200

Single Device object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object or null

Information used to configure how the Device handles transactions.

connection
string

Details if the Device is connected and online. Only returned when include_connection parameter provided.

created_at
string <date-time>

Timestamp of when the object was created.

description
string or null

Additional information about device (e.g. self serving terminal).

enabled
boolean

Details if the Device resource is enabled. Set to false to disable the Device.

id
string

The ID of the activated Device.

idle_message
string or null

The message that diplays on the device after a period of inactivity.

merchant
string

ID of the Merchant resource.

model
string

Details the model of the card reader.

name
string

Name of the Device.

serial_number
string or null

Serial number of the device.

object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/devices/{device_id}
Request samples
Response samples
application/hal+json
{}

Create a Device

Create a Device under a Merchant.

Request
path Parameters
merchant_id
required
string

ID of the Merchant object.

Request Body schema: application/hal+json
object

Configure the details of the activated device.

description
string

Additional information about device (e.g. self serving terminal).

model
required
string

The model type of the device.

Enum: "BBPOS" "MX915" "MX925" "IPP320" "IPP350" "ISC250" "ISC480" "ISMP4" "ANDROID" "LANE_3000" "LINK_2500"
name
required
string

Name of the Device.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
200

Single Device object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object or null

Information used to configure how the Device handles transactions.

connection
string

Details if the Device is connected and online. Only returned when include_connection parameter provided.

created_at
string <date-time>

Timestamp of when the object was created.

description
string or null

Additional information about device (e.g. self serving terminal).

enabled
boolean

Details if the Device resource is enabled. Set to false to disable the Device.

id
string

The ID of the activated Device.

idle_message
string or null

The message that diplays on the device after a period of inactivity.

merchant
string

ID of the Merchant resource.

model
string

Details the model of the card reader.

name
string

Name of the Device.

serial_number
string or null

Serial number of the device.

object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/merchants/{merchant_id}/devices
Request samples
Response samples
application/hal+json
{}