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

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.api+json" \
  -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
Response samples
application/hal+json
{}

Initiate Action on Device

Initiate an action on a Device. Actions that are available include:

  • Activating the Device
  • Rebooting the Device
  • Setting an idle message
  • Deactivating the Device

You can also use a PUT request to update the configuration_details, description, name, and serial_number of the Device.

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.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Device object

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" … 6 more
name
required
string

Name of the Device.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Device object

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
curl https://finix.sandbox-payments-api.com/merchants/MUg1bpb6WZ4a1JLo1pPmA15K/devices \
  -H "Content-Type: application/vnd.api+json" \
  -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X POST \
  -d '
  {
    "configuration": {
      "allow_debit": true,
      "bypass_device_on_capture": true,
      "prompt_signature": "NEVER"
    },
    "description": "John Smith",
    "model": "LANE_7000",
    "name": "Finix Reader #1"
  }'
Response samples
application/hal+json
{}