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": "2023-04-13T01:20:52.209507Z",
  • "updated_at": "2024-12-18T09:32:02.64Z",
  • "android_version": 13,
  • "configuration_details": {
    • "allow_debit": true,
    • "check_for_duplicate_transactions": true,
    • "prompt_amount_confirmation": true,
    • "prompt_manual_entry": false,
    • "prompt_signature": "ALWAYS",
    • "signature_threshold_amount": 0,
    • "bypass_device_on_capture": true,
    • "prompt_receipt_confirmation": null,
    • "display_tip_on_receipt": null,
    • "prompt_tip_on_screen": null,
    • "allow_standalone_authorizations": null,
    • "allow_standalone_sales": null,
    • "allow_standalone_refunds": null,
    • "tipping_details": null,
    • "idle_message": null,
    • "idle_image_file_id": null,
    • "automatic_receipt_delivery_methods": null,
    • "available_receipt_methods": null
    },
  • "description": "Device",
  • "enabled": true,
  • "firmware_version": "2.1.0",
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "MX915",
  • "payment_app_version": "3.2.1",
  • "name": "pytest_device01",
  • "serial_number": null,
  • "tags": {
    • "test_key_101": "test_val_101"
    },
  • "_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",
  • "android_version": 13,
  • "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,
  • "firmware_version": "2.1.0",
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "LANE_3000",
  • "payment_app_version": "3.2.1",
  • "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",
  • "android_version": 13,
  • "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,
  • "firmware_version": "2.1.0",
  • "idle_message": null,
  • "merchant": "MUu56ZGx3Xb6U9gAqKfgNisd",
  • "model": "LANE_3000",
  • "payment_app_version": "3.2.1",
  • "name": "Johnnys Juice Shop",
  • "serial_number": "343434343",
  • "tags": { },
  • "_links": {}
}
List Device Metrics
Finix collects and analyzes data from payment devices and terminals to generate logs, known as Device Metric objects. Each Device Metric log provides insights into device health, network connectivity, and payment processing performance.


Use this endpoint to retrieve a device's Device Metric logs.


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


Request 
path Parameters
device_id
required
string
The device whose logs you wish to view.


 
query Parameters
limit
integer
The numbers of items to return.


 
 Example:  limit=10
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
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
connection
string
Query logs based on the device's connection status (i.e., whether the device has an open or closed connection).


 Enum: "CLOSED" "OPEN"  
 Example:  connection=OPEN
connectivity_network_type
string
Query based on the type of network connection (e.g., Wi-Fi, cellular, ethernet).


 Enum: "CELLULAR" "ETHERNET" "WIFI"  
 Example:  connectivity_network_type=WIFI
connectivity_signal_strength
string
Query based on the network connection strength.


 Enum: "EXCELLENT" "GOOD" "POOR" "VERY_POOR"  
 Example:  connectivity_signal_strength=POOR
event_type
string
Query based on the type of event that triggered the generation of the Device Metric.


 Enum: "APP_BACKGROUNDED" "APP_OPENED" "CHARGE_STATUS" "SCHEDULED_INTERVAL" "SERVER_CONNECTED" … 1 more 
 Example:  event_type=SCHEDULED_INTERVAL
payment_app_state
string
Query based on whether the payment application was running in the background or foreground on the device.


 Enum: "BACKGROUND" "FOREGROUND"  
 Example:  payment_app_state=BACKGROUND
payment_app_version
string
Query based on the exact version of the payment application.


 
 Example:  payment_app_version=3.2.1
payment_app_version.gte
string
Query greater than or equal to the specified payment app version.


 
 Example:  payment_app_version.gte=3.2.1
payment_app_version.lte
string
Query less than or equal to the specified payment app version.


 
 Example:  payment_app_version.lte=3.2.1
power_battery_level_percent
integer
Query the device's battery level percentage.


 
 Example:  power_battery_level_percent=75
power_battery_level_percent.gte
integer
Query greater than or equal to the specified battery level percentage.


 
 Example:  power_battery_level_percent.gte=75
power_battery_level_percent.lte
integer
Query less than or equal to the specified battery level percentage.


 
 Example:  power_battery_level_percent.lte=75
power_battery_temperature_celsius
number <double> 
Query based on the device's battery temperature in Celsius.


 
 Example:  power_battery_temperature_celsius=32.5
power_battery_temperature_celsius.gte
number <double> 
Query greater than or equal to the specified battery temperature in Celsius.


 
 Example:  power_battery_temperature_celsius.gte=32.5
power_battery_temperature_celsius.lte
number <double> 
Query less than or equal to the specified battery temperature in Celsius.


 
 Example:  power_battery_temperature_celsius.lte=32.5
power_battery_temperature_fahrenheit
number <double> 
Query based on the device's battery temperature in Fahrenheit.


 
 Example:  power_battery_temperature_fahrenheit=32.5
power_battery_temperature_fahrenheit.gte
number <double> 
Query greater than or equal to the specified battery temperature in Fahrenheit.


 
 Example:  power_battery_temperature_fahrenheit.gte=32.5
power_battery_temperature_fahrenheit.lte
number <double> 
Query less than or equal to the specified battery temperature in Fahrenheit.


 
 Example:  power_battery_temperature_fahrenheit.lte=32.5
power_is_charging
boolean
Query whether the device was charging or not charging.


 
 Example:  power_is_charging=true
system_android_version
string
Query based on the Android operating system version installed on the device.


 
 Example:  system_android_version=12
system_android_version.gte
string
Query greater than or equal to the specified Android operating system version.


 
 Example:  system_android_version.gte=12
system_android_version.lte
string
Query less than or equal to the specified Android operating system version.


 
 Example:  system_android_version.lte=12
system_firmware_version
string
Query based on the firmware version.


 
 Example:  system_firmware_version=2.1.0
system_firmware_version.gte
string
Query greater than or equal to the specified firmware version.


 
 Example:  system_firmware_version.gte=2.1.0
system_firmware_version.lte
string
Query less than or equal to the specified firmware version.


 
 Example:  system_firmware_version.lte=2.1.0
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
Responses 
200
List of Device Metric objects.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/devices/{device_id}/device_metrics
Request samples 
curl "https://finix.sandbox-payments-api.com/devices/DVpVpNmhsoyM6uShH6aobC22/device_metrics" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples 
application/json
{
  • "_embedded": {
    • "device_metrics": [
      ],
    • "_links": {},
    • "page": {
      }
    }
}
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",
  • "android_version": 13,
  • "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,
  • "firmware_version": "2.1.0",
  • "idle_message": null,
  • "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  • "model": "PAX_A800",
  • "payment_app_version": "3.2.1",
  • "name": "My PAX_A800 Finix Device",
  • "serial_number": "19046260945",
  • "tags": { },
  • "_links": {}
}