Sign in
Devices

Create a Merchant Device

Create a Device under a Merchant.

post/merchants/{merchant_id}/devices

Path parameters

merchant_idstring required

The ID of the Merchant the Device will be created under.

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

app_bundle_idstring

The Apple app bundle identifier for the iOS app that will use the Device. Required when model is IOS_TAP_TO_PAY.

descriptionstring

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

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.

model'IOS_TAP_TO_PAY' | 'PAX_A800' | 'PAX_A920PRO' | 'PAX_D135' | 'PAX_IM30' required

The model type of the Device.

namestring required

Name of the Device.

serial_numberstring required

The serial number of the Device.

tagsTags 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)

Response

Request to create a device under a merchant.

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

android_versionstring

The Android version installed on the Device.

descriptionstring nullable

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

enabledboolean

Whether the Device is enabled. false indicates disabled.

firmware_versionstring

The current version of the device's firmware.

idle_messagestring 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_idstring 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.

merchantstring

ID of the Merchant resource.

model'IOS_TAP_TO_PAY' | 'PAX_A35' | 'PAX_A800' | 'PAX_A3700' | 'PAX_A920PRO' | 'PAX_D135' | 'PAX_IM30'

The model type of the Device.

namestring

The display name of the Device used for filtering purposes.

payment_app_versionstring

The device’s current app version.

prompt_signature'ALWAYS'

When to prompt for a signature.

serial_numberstring 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.

tagsTags 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)

Example response

{
  "merchant": "MUxxxxxxxxxxxxxxxxxx"
}

Changes

Changed in 3 of the 9 revisions of this API.1207

  • 96653f0c196b1175See the full diff
    • ▲

      the configuration response's property type/format changed from object/ to / for status 201

      response-property-type-changed

    • ●

      removed the optional property configuration/allow_debit from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/allow_standalone_authorizations from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/allow_standalone_refunds from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/allow_standalone_sales from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/bypass_device_on_capture from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/check_for_duplicate_transactions from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/display_tip_on_receipt from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/idle_image_file_id from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/idle_message from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/prompt_amount_confirmation from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/prompt_for_signature from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/prompt_manual_entry from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/prompt_receipt_confirmation from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/prompt_tip_on_screen from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/signature_threshold_amount from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/surcharge_basis_points from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property configuration/tipping_details from the response with the 201 status

      response-optional-property-removed

    • ○

      added the new optional request property configuration/automatic_receipt_delivery_methods

      new-optional-request-property

    • ○

      added the new optional request property configuration/available_receipt_methods

      new-optional-request-property

    • ○

      the request property configuration/surcharge_basis_points became nullable

      request-property-became-nullable

    • ○

      added the optional property configuration_details to the response with the 201 status

      response-optional-property-added

    • ○

      added device_configuration to the configuration response property allOf list for the response status 201

      response-property-all-of-added

  • 3173732208e412See the full diff
    • ●

      added the new IOS_TAP_TO_PAY enum value to the model response property for the response status 201

      response-property-enum-value-added

    • ○

      added the new optional request property app_bundle_id

      new-optional-request-property

    • ○

      added the new IOS_TAP_TO_PAY enum value to the request property model

      request-property-enum-value-added

  • 425a15f60e062See the full diff
    • ●

      added the new PAX_A35 enum value to the model response property for the response status 201

      response-property-enum-value-added

    • ●

      added the new PAX_A3700 enum value to the model response property for the response status 201

      response-property-enum-value-added