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
{}

Update Device

You can either update the configuration of a device or take an action on the device

Terminals must be online and connected to the network in order for the request to be successful.

You can initiate an action on a Device. Actions supported vary by gateway.

FINIX_V1 and DUMMY_V1 terminals support the following actions:

  • ACTIVATE - Activate the device to enable processing
  • DEACTIVATE - Deactivate the device to disable processing
  • CANCEL - Cancel any active transaction and return to the idle screen

DATACAP_V1 terminals support the following actions:

  • ACTIVATE - Activate the device to enable processing
  • DEACTIVATE - Deactivate the device to disable processing

TRIPOS_CLOUD_V1 terminals support following actions:

  • ACTIVATE - Activate the device to enable processing
  • DEACTIVATE - Deactivate the device to disable processing
  • CREATE_IDLE_MESSAGE - Update the idle message content on the terminal
  • REBOOT - Remotely reboot the terminal

You can also use a PUT request to update the configuration_details, description, name, and serial_number of the Device. Functionality varies by gateway/device.

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
{}
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
{}