List Devices

Retrieve a list of Devices.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
limit
integer

The numbers of items to return.

Example: limit=10
created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
updated_at.gte
string <date-time>

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
after_cursor
string

Return every resource created after the cursor value.

Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string

Return every resource created before the cursor value.

Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
tags.key
string

Filter by the tag's key. For more information, see Tags.

Example: tags.key=card_type
tags.value
string

Filter by the tag's value. For more information, see Tags.

Example: tags.value=business_card
application_id
string

Filter by Application ID.

Example: application_id=APgPDQrLD52TYvqazjHJJchM
merchant_id
string

Filter by Merchant ID.

Example: merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs
name
string

Filter by the name.

Example: name=john%%20smith
model
string

Filter by the model.

Example: model=MX915
description
string

Filter by the description.

Example: description=Finix%%20Description
serial_number
string

Filter by the serial number.

Example: serial_number=343434343
enabled
boolean

Filter by the enabled value.

Example: enabled=true
header Parameters
Accept
string
Default: application/hal+json

Body Header

Responses
200

List of Device objects

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

get/devices
Request samples 
curl "https://finix.sandbox-payments-api.com/devices" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
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
{
  • "id": "DVsEanpBtsAVvCHbNXkFaH6f",
  • "created_at": "2019-03-01T02:27:20.366Z",
  • "updated_at": "2022-04-05T18:48:40.383Z",
  • "configuration_details": {
    • "allow_debit": true,
    • "allow_standalone_authorizations": null,
    • "allow_standalone_refunds": null,
    • "allow_standalone_sales": null,
    • "automatic_receipt_delivery_methods": null,
    • "available_receipt_methods": null,
    • "bypass_device_on_capture": true,
    • "check_for_duplicate_transactions": true,
    • "display_tip_on_receipt": null,
    • "idle_message": null,
    • "idle_image_file_id": null,
    • "prompt_amount_confirmation": false,
    • "prompt_manual_entry": true,
    • "prompt_receipt_confirmation": null,
    • "prompt_tip_on_screen": false,
    • "tipping_details": {
      }
    },
  • "description": "Mike Jones",
  • "enabled": false,
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "MX915",
  • "name": "Johnnys Juice Shop",
  • "serial_number": "343434343",
  • "tags": { },
  • "_links": {}
}

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.

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. (For example, order_number: 25, item_type: produce, department: sales)
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
{
  • "id": "DVsEanpBtsAVvCHbNXkFaH6f",
  • "created_at": "2019-03-01T02:27:20.366Z",
  • "updated_at": "2022-04-05T18:48:40.383Z",
  • "configuration_details": {
    • "allow_debit": true,
    • "check_for_duplicate_transactions": true,
    • "prompt_amount_confirmation": false,
    • "prompt_manual_entry": true,
    • "bypass_device_on_capture": true,
    • "prompt_receipt_confirmation": null,
    • "display_tip_on_receipt": null,
    • "prompt_tip_on_screen": false,
    • "allow_standalone_authorizations": null,
    • "allow_standalone_sales": null,
    • "allow_standalone_refunds": null,
    • "tipping_details": {
      },
    • "idle_message": null,
    • "idle_image_file_id": null,
    • "automatic_receipt_delivery_methods": null,
    • "available_receipt_methods": null
    },
  • "description": "Mike Jones",
  • "enabled": true,
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "LANE_3000",
  • "name": "Johnnys Juice Shop",
  • "serial_number": "343434343",
  • "tags": { },
  • "_links": {}
}
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
Response examples for requests to check device connection.


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
{
  • "id": "DVsEanpBtsAVvCHbNXkFaH6f",
  • "created_at": "2019-03-01T02:27:20.366Z",
  • "updated_at": "2022-04-05T18:48:40.383Z",
  • "configuration_details": {
    • "allow_debit": true,
    • "check_for_duplicate_transactions": true,
    • "prompt_amount_confirmation": false,
    • "prompt_manual_entry": true,
    • "bypass_device_on_capture": true,
    • "prompt_receipt_confirmation": null,
    • "display_tip_on_receipt": null,
    • "prompt_tip_on_screen": false,
    • "allow_standalone_authorizations": null,
    • "allow_standalone_sales": null,
    • "allow_standalone_refunds": null,
    • "tipping_details": {
      },
    • "idle_message": null,
    • "idle_image_file_id": null,
    • "automatic_receipt_delivery_methods": null,
    • "available_receipt_methods": null
    },
  • "connection": "OPEN",
  • "description": "Mike Jones",
  • "enabled": true,
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "LANE_3000",
  • "name": "Johnnys Juice Shop",
  • "serial_number": "343434343",
  • "tags": { },
  • "_links": {}
}
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
required
object
Information used to configure how the Device handles transaction flows.


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


 
model
required
string
The model type of the Device.


 Enum: "PAX_A800" "PAX_A920PRO" "D135"  
name
required
string
Name of the Device.


 
serial_number
required
string
The serial number 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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
200
Response to a request for creating a Device under a Merchant.


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/json
{
  • "id": "DV7DvjGoZ2AEdhAKhtKXVv4b",
  • "created_at": "2024-10-24T01:17:37.616233Z",
  • "updated_at": "2024-10-24T01:17:37.616233Z",
  • "configuration_details": {
    • "allow_debit": true,
    • "check_for_duplicate_transactions": true,
    • "prompt_amount_confirmation": true,
    • "prompt_manual_entry": false,
    • "bypass_device_on_capture": true,
    • "prompt_receipt_confirmation": true,
    • "display_tip_on_receipt": false,
    • "prompt_tip_on_screen": false,
    • "allow_standalone_authorizations": false,
    • "allow_standalone_sales": false,
    • "allow_standalone_refunds": false,
    • "tipping_details": {
      },
    • "idle_message": null,
    • "idle_image_file_id": null,
    • "automatic_receipt_delivery_methods": null,
    • "available_receipt_methods": null
    },
  • "description": "Cashier One",
  • "enabled": false,
  • "idle_message": null,
  • "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  • "model": "PAX_A800",
  • "name": "My PAX_A800 Finix Device",
  • "serial_number": "19046260945",
  • "tags": { },
  • "_links": {}
}