Skip to content

Device Idle Image

By default, Finix terminals display a standard welcome screen when idle. You can replace the default idle screen image with your own logo or image using the Finix Dashboard or API.

Using the Finix Dashboard

You can replace the default idle screen image on the Finix Dashboard.

  1. From the Device Management screen, click the device you want to update from the device list.
Device management list page
  1. From the device details screen, click Edit in the Idle Screen section.
Device details page - edit idle screen
  1. In the Update Idle Screen modal, upload your idle screen image. Optionally provide an idle message to display along with the idle screen image.
Device details page - update idle screen modal

The next time the device goes idle, your idle screen image displays instead of the default idle screen.

To reset the idle screen to the default, click Reset from the Update Idle Screen modal.

Using the API

To replace the default idle screen image using the API, you must:

  1. Create a File resource.
  2. Upload the idle image to the File resource.
  3. Verify the image file is approved.
  4. Update the Device resource to use the idle image.
Image file vs. the File resource

Your image file is not the same as a File resource. Create a File resource first to obtain an ID, then use that ID to upload your image file to it.

1. Create a File resource

Send a POST /files request to create a File resource.

In the request, include the following fields:

  • linked_to - The Merchant id.
  • type - Set to DEVICE_IDLE_IMAGE.
  • display_name - A human-readable name for the File.
Create a File resource for device idle image
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/files \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "display_name": "Custom device idle image",
    "linked_to": "MUvWVhLpLj9w7kV1EXA7yvzc",
    "type": "DEVICE_IDLE_IMAGE"
  }'

A successful request returns a 201 Created status with the response body containing the newly created File resource. The REQUIRES_UPLOAD status indicates that the image upload step is still pending.

Save the resource id for the next step.

{
  "id" : "FILE_eUN3CgqaEiYS84QhrDy42T",
  "status" : "REQUIRES_UPLOAD",
  "created_at" : "2026-09-16T22:58:39.586982Z",
  "updated_at" : "2026-09-16T22:58:39.586982Z",
  "linked_type" : "MERCHANT",
  "linked_to" : "MUvWVhLpLj9w7kV1EXA7yvzc",
  "extension" : null,
  "display_name" : "Custom device idle image",
  "type" : "DEVICE_IDLE_IMAGE",
  "platform_id" : "PLoMxXWbqwEMT5N1upSaNUbJ",
  "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "tags" : { },
  "identity_id" : "IDnT3ff71VShf6dB2ShcPozq",
  "entity_id" : null,
  "entity_type" : null,
  "size_in_bytes" : null,
  "file_name" : null
}

2. Upload the device idle image

Send a POST /files/{file_id}/upload request as multipart/form-data, using the File resource id from the previous step.

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/files/FILE_eUN3CgqaEiYS84QhrDy42T/upload \
  -H 'Content-Type: multipart/form-data' \
  -H 'Finix-Version: 2022-02-01' \
  -F file=@/Users/Desktop/device-idle-image.png

3. Verify the image is approved

Wait until the File resource reports status: UPLOADED before assigning it to a device. You can confirm the status in one of two ways:

  • Poll for status: Send a GET /files/{file_id} request and check the status field in the response.
  • Subscribe to webhooks: Register a webhook to receive a notification when the File's status changes.

4. Update device idle image

Now that the image is approved, update the Device resource by sending a PUT /devices/{device_id} request with your custom idle image.

You can also customize the text shown on the idle screen using the idle_message field.

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/devices/DVoDo7F6yYCnX2d6Fj9hvsd \
  -H 'Content-Type: application/json' \
  -d '{
    "configuration": {
      "idle_image_file_id": "FILE_bFSshq8CFdm1wyTJQztys7",
      "idle_message": "Device is idle"
    }
  }'

A successful request returns a 200 OK status with the response body containing the Device with the updated idle image and idle message.

The next time the device goes idle, your idle screen image displays instead of the default idle screen.

To reset the idle screen to the default, send a PUT /devices/{device_id} request with configuration.idle_image_file_id set to null.