Initiate Action on Device

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

  • Activating the Device
  • Deactivating the Device
  • Cancel an activity on the Device

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

Terminals must be online and connected to the network in order for the request to be successful. Actions supported vary by gateway.

FINIX_V1 terminals support the following actions:

  • ACTIVATE
  • DEACTIVATE
  • CANCEL

DATACAP_V1 terminals support the following actions:

  • ACTIVATE
  • DEACTIVATE

TRIPOS_CLOUD_V1 terminals support following actions:

  • ACTIVATE
  • DEACTIVATE
  • CREATE_IDLE_MESSAGE
Request
path Parameters
device_id
required
string

ID of the Device.

header Parameters
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Accept
string
Default: application/hal+json
Request Body schema: application/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"
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/json
{}

Fetch a Device

Retrieve the details of an existing Device.

Request
path Parameters
device_id
required
string

ID of the Device.

query Parameters
include_connection
boolean

Specifies whether the connection information should be included.

header Parameters
Accept
string
Default: application/hal+json
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/DVsEanpBtsAVvCHbNXkFaH6f" \
  -H "Finix-Version: 2022-02-01" \
  -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
Response samples
application/json
{}

Check Device Connection

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

Request
path Parameters
device_id_connection
required
string
query Parameters
include_connection
required
boolean

Specifies whether the connection information should be included.

header Parameters
Accept
string
Default: application/hal+json
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_connection}
Request samples
curl "https://finix.sandbox-payments-api.com/devices/DVsEanpBtsAVvCHbNXkFaH6f?include_connection=true" \
  -H "Finix-Version: 2022-02-01" \
  -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
Response samples
application/json
{}

Create a Device

Create a Device under a Merchant.

Request
path Parameters
merchant_id
required
string

ID of the Merchant object.

header Parameters
Accept
string
Default: application/hal+json
Request Body schema: application/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" "DESK_3500" "DESK_5000" "IPP320" "IPP350" … 21 more
name
required
string

Name of the Device.

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/json" \
  -H "Finix-Version: 2022-02-01" \
  -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/json
{}