--- title: "Update Device" method: PUT path: "/devices/{device_id}" tags: ["Devices"] --- # Update Device `PUT /devices/{device_id}` 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 For processors other than `FINIX_V1` and `DUMMY_V1`, contact your Finix point of contact or email [Finix Support](/guides/getting-started/support-at-finix/) for device update instructions. You can also use a PUT request to update the `configuration`, `description`, `name`, and `serial_number` of the `Device`. ## Request body - union - object - `action` 'ACTIVATE', required — The action you want to perform on the device. Use **ACTIVATE** to activate a the physical model with the `Device`. - `tags` Tags, nullable — 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`) - object - `action` 'CANCEL', required — The action you want to perform on the device. Use `CANCEL` to cancel any active transaction and return to the idle screen. - `tags` Tags, nullable — 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`) - object - `action` 'DEACTIVATE', required — The action you want to perform on the device. Use **DEACTIVATE** to deactivate the device. - object - `configuration` DeviceConfiguration — Information used to configure how the `Device` handles transaction flows. - `allow_debit` boolean — Enable processing of transactions through Debit rails. If set to `false`, Debit card transactions will instead be processed through Credit rails. - `allow_standalone_authorizations` boolean — Sets whether the device allows initialization authorizations on its interface.`FINIX_V1` and `DUMMY_V1` only. - `allow_standalone_refunds` boolean — Sets whether the device allows initialization refunds on its interface. `FINIX_V1` and `DUMMY_V1` only. - `allow_standalone_sales` boolean — Sets whether the device allows initialization sales on its interface. - `bypass_device_on_capture` boolean, nullable — Sets whether or not the device will be used to capture transactions. This field should be set to `true` unless there are special circumstances. - `check_for_duplicate_transactions` boolean — Sets if the device will check for duplicate transactions. `DATACAP_V1` only. - `display_tip_on_receipt` boolean — Sets whether the device will display the blank tip amount on the receipt for authorizations to be later captured. `FINIX_V1` and `DUMMY_V1` only. - `idle_image_file_id` string, nullable — The ID of the file to be displayed on the device when it is idle. Passing a value of `null` resets the device's idle image to the default. - `idle_message` string, nullable — Sets the idle message text on the terminal. This is what will be presented on the welcome screen. `FINIX_V1` and `DUMMY_V1` only. - `prompt_amount_confirmation` boolean — Sets if the cardholder needs to confirm the amount they'll pay. `DATACAP_V1` only. - `prompt_for_signature` 'ALWAYS' | 'NEVER' | 'ON_NETWORK_RECOMMENDATION' | 'ON_THRESHOLD_AMOUNT' — Determines when the terminal prompts for an e-signature. - `ALWAYS`: The terminal will always request an e-signature. - `NEVER`: The terminal will never request an e-signature. - `ON_NETWORK_RECOMMENDATION`: The terminal follows card network recommendations on whether to prompt for a signature. - `ON_THRESHOLD_AMOUNT`: The terminal requests an e-signature only when the transaction amount is greater than or equal to `signature_threshold_amount`. - `prompt_manual_entry` boolean — Sets if the device allows for manual entry as a card input method. `DATACAP_V1` and `FINIX_V1` only. On `DATACAP_V1` if this is set to true manual entry will be the default entry option. - `prompt_receipt_confirmation` boolean — Sets whether or not the device presents a screen prompting the buyer to print receipt at the end of the transaction flow. `FINIX_V1` and `DUMMY_V1` only. - `prompt_tip_on_screen` boolean — Sets whether the device will display the suggested tipping screen. `FINIX_V1` and `DUMMY_V1` only. - `signature_threshold_amount` unknown - `surcharge_basis_points` integer — Represents the transaction amount that a `Merchant` charges the buyer when creating a `Transfer` or an `Authorization`. The value cannot exceed `300` (i.e., 3%). For devices on Standalone Mode, the Finix Payment Application on the terminal will calculate and send a `Transfer` or an `Authorization` request with the surcharge added. Customers integrated directly into Finix API must contact Support to incorporate surcharging appropriately into their integration. - `tipping_details` object — An object that sets the configurations for the tipping page if it appears. `FINIX_V1` and `DUMMY_V1` only. - `allow_custom_tip` boolean — Allows the buyer to set a custom tip. `FINIX_V1` and `DUMMY_V1` only. - `fixed_options` unknown[] — Sets the fixed amount that will be displayed on the terminal. Defaults to `[100, 150, 200]`. Must be three integer values that represent cent values. `FINIX_V1` and `DUMMY_V1` only. - unknown - `percent_options` unknown[] — Sets the percentages that will be displayed on the terminal. Defaults to `[18, 20, 22]`. Must be three integer values that represent percentages. `FINIX_V1` and `DUMMY_V1` only. - unknown - `percent_tipping_threshold` integer — The inclusive value at which the terminal will present a percent based prompt instead of a fixed value prompt. Defaults to `false`. `FINIX_V1` and `DUMMY_V1` only. - `description` string — Additional information about device (e.g. self serving terminal). - `name` string — Name of the `Device`. - `serial_number` string — Serial number of the `device`. - object - `surcharge_basis_points` integer — Represents the transaction amount that a `Merchant` charges the buyer when creating a `Transfer` or an `Authorization`. The value cannot exceed `300` (i.e., 3%). For devices on Standalone Mode, the Finix Payment Application on the terminal will calculate and send a `Transfer` or an `Authorization` request with the surcharge added. Customers integrated directly into Finix API must contact Support to incorporate surcharging appropriately into their integration. - object - `idle_image_file_id` string, nullable — The ID of the file to be displayed on the device when it is idle. Passing a value of `null` resets the device's idle image to the default. ## Response `200` A single `Device` - Device - `id` string — The ID of the resource. - `created_at` string, date-time — Timestamp of when the object was created. - `updated_at` string, date-time — Timestamp of when the object was last updated. - `android_version` string — The Android version installed on the `Device`. - `configuration` DeviceConfiguration — Information used to configure how the `Device` handles transaction flows. - `allow_debit` boolean — Enable processing of transactions through Debit rails. If set to `false`, Debit card transactions will instead be processed through Credit rails. - `allow_standalone_authorizations` boolean — Sets whether the device allows initialization authorizations on its interface.`FINIX_V1` and `DUMMY_V1` only. - `allow_standalone_refunds` boolean — Sets whether the device allows initialization refunds on its interface. `FINIX_V1` and `DUMMY_V1` only. - `allow_standalone_sales` boolean — Sets whether the device allows initialization sales on its interface. - `bypass_device_on_capture` boolean, nullable — Sets whether or not the device will be used to capture transactions. This field should be set to `true` unless there are special circumstances. - `check_for_duplicate_transactions` boolean — Sets if the device will check for duplicate transactions. `DATACAP_V1` only. - `display_tip_on_receipt` boolean — Sets whether the device will display the blank tip amount on the receipt for authorizations to be later captured. `FINIX_V1` and `DUMMY_V1` only. - `idle_image_file_id` string, nullable — The ID of the file to be displayed on the device when it is idle. Passing a value of `null` resets the device's idle image to the default. - `idle_message` string, nullable — Sets the idle message text on the terminal. This is what will be presented on the welcome screen. `FINIX_V1` and `DUMMY_V1` only. - `prompt_amount_confirmation` boolean — Sets if the cardholder needs to confirm the amount they'll pay. `DATACAP_V1` only. - `prompt_for_signature` 'ALWAYS' | 'NEVER' | 'ON_NETWORK_RECOMMENDATION' | 'ON_THRESHOLD_AMOUNT' — Determines when the terminal prompts for an e-signature. - `ALWAYS`: The terminal will always request an e-signature. - `NEVER`: The terminal will never request an e-signature. - `ON_NETWORK_RECOMMENDATION`: The terminal follows card network recommendations on whether to prompt for a signature. - `ON_THRESHOLD_AMOUNT`: The terminal requests an e-signature only when the transaction amount is greater than or equal to `signature_threshold_amount`. - `prompt_manual_entry` boolean — Sets if the device allows for manual entry as a card input method. `DATACAP_V1` and `FINIX_V1` only. On `DATACAP_V1` if this is set to true manual entry will be the default entry option. - `prompt_receipt_confirmation` boolean — Sets whether or not the device presents a screen prompting the buyer to print receipt at the end of the transaction flow. `FINIX_V1` and `DUMMY_V1` only. - `prompt_tip_on_screen` boolean — Sets whether the device will display the suggested tipping screen. `FINIX_V1` and `DUMMY_V1` only. - `signature_threshold_amount` unknown - `surcharge_basis_points` integer — Represents the transaction amount that a `Merchant` charges the buyer when creating a `Transfer` or an `Authorization`. The value cannot exceed `300` (i.e., 3%). For devices on Standalone Mode, the Finix Payment Application on the terminal will calculate and send a `Transfer` or an `Authorization` request with the surcharge added. Customers integrated directly into Finix API must contact Support to incorporate surcharging appropriately into their integration. - `tipping_details` object — An object that sets the configurations for the tipping page if it appears. `FINIX_V1` and `DUMMY_V1` only. - `allow_custom_tip` boolean — Allows the buyer to set a custom tip. `FINIX_V1` and `DUMMY_V1` only. - `fixed_options` unknown[] — Sets the fixed amount that will be displayed on the terminal. Defaults to `[100, 150, 200]`. Must be three integer values that represent cent values. `FINIX_V1` and `DUMMY_V1` only. - unknown - `percent_options` unknown[] — Sets the percentages that will be displayed on the terminal. Defaults to `[18, 20, 22]`. Must be three integer values that represent percentages. `FINIX_V1` and `DUMMY_V1` only. - unknown - `percent_tipping_threshold` integer — The inclusive value at which the terminal will present a percent based prompt instead of a fixed value prompt. Defaults to `false`. `FINIX_V1` and `DUMMY_V1` only. - `description` string, nullable — Additional information about device (e.g. self serving terminal). - `enabled` boolean — Whether the `Device` is enabled. `false` indicates disabled. - `firmware_version` string — The current version of the device's firmware. - `idle_message` string, nullable — Sets the idle message text on the terminal. This is what will be presented on the welcome screen. `FINIX_V1` and `DUMMY_V1` only. - `idle_image_file_id` string, nullable — The ID of the file to be displayed on the device when it is idle. Passing a value of `null` resets the device's idle image to the default. - `integration_mode` 'PAYMENT_APP' | 'SDK' — Defines the operating mode of the `Device`. `PAYMENT_APP` devices operate within the standard Finix ecosystem. `SDK` devices are for customers who are building their own PAX app. - `merchant` string — ID of the `Merchant` resource. - `model` 'PAX_A800' | 'PAX_A920PRO' | 'PAX_D135' | 'PAX_IM30' — The model type of the `Device`. - `name` string — The display name of the `Device` used for filtering purposes. - `payment_app_version` string — The device’s current app version. - `prompt_signature` 'ALWAYS' — When to prompt for a signature. - `serial_number` string, nullable — The serial_number is a unique identifier for the `Device`, located on the back and typically composed of ~16 digits. Ensure the serial number is set before activating the `Device`, though it can also be added later using a PUT request. - `tags` Tags, nullable — 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`) - `_links` object — For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs. - `authorizations` object - `href` string - `merchant` object — Link to the `Merhcant` resource that was used in the request. - `href` string - `self` object — Link to the resource that was used in the request. - `href` string - `transfers` object - `href` string ## Other responses - `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data. - `401` — Unauthorized. Authentication is required and has failed or has not been provided. - `403` — Forbidden. The client is authenticated but does not have permission to access the resource. - `404` — Not Found. The requested resource could not be found on the server. - `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted. --- [API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)