{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml","oas-api/index.yaml":"oas-api/index.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img","ApiLink","admonition","tabs","tab","openapi-code-sample","json-schema"]},"type":"markdown"},"seo":{"title":"Device Idle Image | Finix Documentation","description":"Configure your brand logo as the custom idle image on PAX terminals.","siteUrl":"https://docs.finix.com/","llmstxt":{"hide":false,"sections":[{"title":"Getting Started","includeFiles":["guides/getting-started/**/*.md"],"excludeFiles":[]},{"title":"Online Payments","includeFiles":["guides/online-payments/**/*.md"],"excludeFiles":["guides/online-payments/payment-features/fsa-hsa-non-healthcare-mcc.md"]},{"title":"In-Person Payments","includeFiles":["guides/in-person-payments/**/*.md"],"excludeFiles":[]},{"title":"Subscriptions","includeFiles":["guides/subscriptions/**/*.md"],"excludeFiles":[]},{"title":"After the Payment","includeFiles":["guides/after-the-payment/**/*.md"],"excludeFiles":[]},{"title":"Managing Operations","includeFiles":["guides/managing-operations/**/*.md"],"excludeFiles":[]},{"title":"Platform Payments","includeFiles":["guides/platform-payments/**/*.md"],"excludeFiles":[]},{"title":"Payouts","includeFiles":["guides/payouts/**/*.md"],"excludeFiles":[]},{"title":"Low-Code / No-Code","includeFiles":["low-code-no-code/**/*.md"],"excludeFiles":[]},{"title":"Developers","includeFiles":["additional-resources/developers/**/*.md"],"excludeFiles":[]},{"title":"Plugins","includeFiles":["additional-resources/plugins/**/*.md"],"excludeFiles":[]},{"title":"Industry Considerations","includeFiles":["guides/industry-considerations/**/*.md"],"excludeFiles":[]},{"title":"Regional Considerations","includeFiles":["guides/regional-considerations/**/*.md"],"excludeFiles":[]},{"title":"Release Notes","includeFiles":["release-notes/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"device-idle-image","__idx":0},"children":["Device Idle Image"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-the-finix-dashboard","__idx":1},"children":["Using the Finix Dashboard"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can replace the default idle screen image on the Finix Dashboard."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["From the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Device Management"]}," screen, click the device you want to update from the device list."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/device-management-device-list.a99de7633e39b26aa76600e7f739348654bcbd8ff482bd4e38e83945bbd62bcc.08ff7529.png","alt":"Device management list page","withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["From the device details screen, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Edit"]}," in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idle Screen"]}," section."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/device-details-idle-screen-edit.0a09a188803bb21f359b2bf27668132e27e861b93c5105d7dc6c972203620db1.08ff7529.png","alt":"Device details page - edit idle screen","withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Idle Screen"]}," modal, upload your idle screen image. Optionally provide an idle message to display along with the idle screen image."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/device-details-idle-screen-update-modal.d5a3554f21a960527c54075f0f0e81aa988505d4576660f81c53c889a995dcd3.08ff7529.png","alt":"Device details page - update idle screen modal","withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The next time the device goes idle, your idle screen image displays instead of the default idle screen."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To reset the idle screen to the default, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reset"]}," from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Idle Screen"]}," modal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-the-api","__idx":2},"children":["Using the API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To replace the default idle screen image using the API, you must:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/files"},"children":["File"]}," resource."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload the idle image to the File resource."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the image file is approved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update the ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/devices"},"children":["Device"]}," resource to use the idle image."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Image file vs. the File resource"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your image file is not the same as a File resource. ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#1-create-a-file-resource"},"children":["Create a File resource"]}," first to obtain an ID, then use that ID to upload your image file to it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-create-a-file-resource","__idx":3},"children":["1. Create a File resource"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/files/createfile"},"children":["POST /files"]}," request to create a File resource."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the request, include the following fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linked_to"]}," - The ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/merchants"},"children":["Merchant"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," - Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEVICE_IDLE_IMAGE"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display_name"]}," - A human-readable name for the File."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","data-title":"Create a File resource for device idle image","header":{"title":"Create a File resource for device idle image","controls":{"copy":{}}},"source":"curl -i -X POST \\\n  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \\\n  https://finix.sandbox-payments-api.com/files \\\n  -H 'Content-Type: application/json' \\\n  -H 'Finix-Version: 2022-02-01' \\\n  -d '{\n    \"display_name\": \"Custom device idle image\",\n    \"linked_to\": \"MUvWVhLpLj9w7kV1EXA7yvzc\",\n    \"type\": \"DEVICE_IDLE_IMAGE\"\n  }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," status with the response body containing the newly created ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/files"},"children":["File"]}," resource. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUIRES_UPLOAD"]}," status indicates that the image upload step is still pending."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the resource ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," for the next step."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\" : \"FILE_eUN3CgqaEiYS84QhrDy42T\",\n  \"status\" : \"REQUIRES_UPLOAD\",\n  \"created_at\" : \"2026-09-16T22:58:39.586982Z\",\n  \"updated_at\" : \"2026-09-16T22:58:39.586982Z\",\n  \"linked_type\" : \"MERCHANT\",\n  \"linked_to\" : \"MUvWVhLpLj9w7kV1EXA7yvzc\",\n  \"extension\" : null,\n  \"display_name\" : \"Custom device idle image\",\n  \"type\" : \"DEVICE_IDLE_IMAGE\",\n  \"platform_id\" : \"PLoMxXWbqwEMT5N1upSaNUbJ\",\n  \"application_id\" : \"APc9vhYcPsRuTSpKD9KpMtPe\",\n  \"tags\" : { },\n  \"identity_id\" : \"IDnT3ff71VShf6dB2ShcPozq\",\n  \"entity_id\" : null,\n  \"entity_type\" : null,\n  \"size_in_bytes\" : null,\n  \"file_name\" : null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-upload-the-device-idle-image","__idx":4},"children":["2. Upload the device idle image"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/files/uploadfile"},"children":["POST /files/{file_id}/upload"]}," request as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},", using the File resource ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," from the previous step."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \\\n  https://finix.sandbox-payments-api.com/files/FILE_eUN3CgqaEiYS84QhrDy42T/upload \\\n  -H 'Content-Type: multipart/form-data' \\\n  -H 'Finix-Version: 2022-02-01' \\\n  -F file=@/Users/Desktop/device-idle-image.png\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-verify-the-image-is-approved","__idx":5},"children":["3. Verify the image is approved"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wait until the File resource reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: UPLOADED"]}," before assigning it to a device. You can confirm the status in one of two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Poll for status:"]}," Send a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/files/uploadfile"},"children":["GET /files/{file_id}"]}," request and check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field in the response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Subscribe to webhooks:"]}," Register a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/additional-resources/developers/webhooks/webhook-events#file-approved"},"children":["webhook"]}," to receive a notification when the File's status changes."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-update-device-idle-image","__idx":6},"children":["4. Update device idle image"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that the image is approved, update the Device resource by sending a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/devices/updatedevice"},"children":["PUT /devices/{device_id}"]}," request with your custom idle image."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also customize the text shown on the idle screen using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idle_message"]}," field."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-api/index.yaml","operationId":"updateDevice","exampleKey":"Device - Update Idle File Image and Message","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"API Definition","disable":false},"children":[{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../../api/components/schemas/requestBodies/devices/updateDeviceIdleFileImageMessage.yaml"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/updateDeviceIdleFileImageMessage"},"updateDeviceIdleFileImageMessage":{"title":"Device - Update Idle File Image and Message","type":"object","properties":{"configuration":{"type":"object","description":"Device configuration settings.","properties":{"idle_image_file_id":{"type":"string","description":"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.","nullable":true},"idle_message":{"type":"string","description":"A message to display when the terminal is idle.","nullable":true}}}}}}}},"schemaResolvedErrors":[]},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," status with the response body containing the ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/devices"},"children":["Device"]}," with the updated idle image and idle message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The next time the device goes idle, your idle screen image displays instead of the default idle screen."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To reset the idle screen to the default, send a ",{"$$mdtype":"Tag","name":"ApiLink","attributes":{"href":"/api/devices/updatedevice"},"children":["PUT /devices/{device_id}"]}," request with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configuration.idle_image_file_id"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},"headings":[{"value":"Device Idle Image","id":"device-idle-image","depth":1},{"value":"Using the Finix Dashboard","id":"using-the-finix-dashboard","depth":2},{"value":"Using the API","id":"using-the-api","depth":2},{"value":"1. Create a File resource","id":"1-create-a-file-resource","depth":3},{"value":"2. Upload the device idle image","id":"2-upload-the-device-idle-image","depth":3},{"value":"3. Verify the image is approved","id":"3-verify-the-image-is-approved","depth":3},{"value":"4. Update device idle image","id":"4-update-device-idle-image","depth":3}],"frontmatter":{"seo":{"title":"Device Idle Image | Finix Documentation","description":"Configure your brand logo as the custom idle image on PAX terminals."},"keywords":{"includes":["idle image","idle screen","logo upload","terminal branding"]}},"lastModified":"2026-10-24T03:32:09.882Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/in-person-payments/device-capabilities/device-idle-image","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}