# Create a Merchant Device

Create a Device under a Merchant.

Endpoint: POST /merchants/{merchant_id}/devices
Version: 2022-02-01
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

  - `Content-Type` (string)
    The data type being sent in the request body must be application/json.
    Example: "application/json"

## Path parameters:

  - `merchant_id` (string, required)
    The ID of the Merchant the Device will be created under.

## Request fields (application/json):

  - `configuration` (object, required)
    Information used to configure how the Device handles transaction flows.

  - `configuration.allow_debit` (boolean)
    Enable processing of transactions through Debit rails. If set to false, Debit card transactions will instead be processed through Credit rails.

  - `configuration.allow_standalone_authorizations` (boolean)
    Sets whether the device allows initialization authorizations on its interface.FINIX_V1 and DUMMY_V1 only.

  - `configuration.allow_standalone_refunds` (boolean)
    Sets whether the device allows initialization refunds on its interface. FINIX_V1 and DUMMY_V1 only.

  - `configuration.allow_standalone_sales` (boolean)
    Sets whether the device allows initialization sales on its interface.

  - `configuration.bypass_device_on_capture` (boolean,null)
    Sets whether or not the device will be used to capture transactions. This field should be set to true unless there are special circumstances.

  - `configuration.check_for_duplicate_transactions` (boolean)
    Sets if the device will check for duplicate transactions. DATACAP_V1 only.

  - `configuration.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.

  - `configuration.idle_image_file_id` (string,null)
    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.

  - `configuration.idle_message` (string,null)
    Sets the idle message text on the terminal. This is what will be presented on the welcome screen. FINIX_V1 and DUMMY_V1 only.

  - `configuration.prompt_amount_confirmation` (boolean)
    Sets if the cardholder needs to confirm the amount they'll pay. DATACAP_V1 only.

  - `configuration.prompt_for_signature` (string)
    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.
    Enum: "ALWAYS", "NEVER", "ON_NETWORK_RECOMMENDATION", "ON_THRESHOLD_AMOUNT"

  - `configuration.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.

  - `configuration.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.

  - `configuration.prompt_tip_on_screen` (boolean)
    Sets whether the device will display the suggested tipping screen. FINIX_V1 and DUMMY_V1 only.

  - `configuration.signature_threshold_amount` (any)
    The transaction amount at which the terminal prompts for an e-signature.

  - `configuration.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.

  - `configuration.tipping_details` (object)
    An object that sets the configurations for the tipping page if it appears. FINIX_V1 and DUMMY_V1 only.

  - `configuration.tipping_details.allow_custom_tip` (boolean)
    Allows the buyer to set a custom tip. FINIX_V1 and DUMMY_V1 only.

  - `configuration.tipping_details.fixed_options` (array)
    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.

  - `configuration.tipping_details.percent_options` (array)
    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.

  - `configuration.tipping_details.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).

  - `model` (string, required)
    The model type of the Device.
    Enum: "PAX_A800", "PAX_A920PRO", "D135"

  - `name` (string, required)
    Name of the Device.

  - `serial_number` (string, required)
    The serial number of the Device.

  - `tags` (object,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)

## Response 201 fields (application/json):

  - `id` (string)
    The ID of the resource.

  - `created_at` (string)
    Timestamp of when the object was created.

  - `updated_at` (string)
    Timestamp of when the object was last updated.

  - `android_version` (string)
    The Android version installed on the Device.

  - `configuration` (object)
    Information used to configure how the Device handles transaction flows.

  - `configuration.allow_debit` (boolean)
    Enable processing of transactions through Debit rails. If set to false, Debit card transactions will instead be processed through Credit rails.

  - `configuration.allow_standalone_authorizations` (boolean)
    Sets whether the device allows initialization authorizations on its interface.FINIX_V1 and DUMMY_V1 only.

  - `configuration.allow_standalone_refunds` (boolean)
    Sets whether the device allows initialization refunds on its interface. FINIX_V1 and DUMMY_V1 only.

  - `configuration.allow_standalone_sales` (boolean)
    Sets whether the device allows initialization sales on its interface.

  - `configuration.bypass_device_on_capture` (boolean,null)
    Sets whether or not the device will be used to capture transactions. This field should be set to true unless there are special circumstances.

  - `configuration.check_for_duplicate_transactions` (boolean)
    Sets if the device will check for duplicate transactions. DATACAP_V1 only.

  - `configuration.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.

  - `configuration.idle_image_file_id` (string,null)
    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.

  - `configuration.idle_message` (string,null)
    Sets the idle message text on the terminal. This is what will be presented on the welcome screen. FINIX_V1 and DUMMY_V1 only.

  - `configuration.prompt_amount_confirmation` (boolean)
    Sets if the cardholder needs to confirm the amount they'll pay. DATACAP_V1 only.

  - `configuration.prompt_for_signature` (string)
    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.
    Enum: "ALWAYS", "NEVER", "ON_NETWORK_RECOMMENDATION", "ON_THRESHOLD_AMOUNT"

  - `configuration.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.

  - `configuration.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.

  - `configuration.prompt_tip_on_screen` (boolean)
    Sets whether the device will display the suggested tipping screen. FINIX_V1 and DUMMY_V1 only.

  - `configuration.signature_threshold_amount` (any)
    The transaction amount at which the terminal prompts for an e-signature.

  - `configuration.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.

  - `configuration.tipping_details` (object)
    An object that sets the configurations for the tipping page if it appears. FINIX_V1 and DUMMY_V1 only.

  - `configuration.tipping_details.allow_custom_tip` (boolean)
    Allows the buyer to set a custom tip. FINIX_V1 and DUMMY_V1 only.

  - `configuration.tipping_details.fixed_options` (array)
    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.

  - `configuration.tipping_details.percent_options` (array)
    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.

  - `configuration.tipping_details.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,null)
    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.

  - `merchant` (string)
    ID of the Merchant resource.
    Example: "MUxxxxxxxxxxxxxxxxxx"

  - `model` (string)
    The model type of the Device.
    Enum: "PAX_A800", "PAX_A920PRO", "D135"

  - `name` (string)
    The display name of the Device used for filtering purposes.

  - `payment_app_version` (string)
    The device’s current app version.

  - `prompt_signature` (string)
    When to prompt for a signature.
    Enum: "ALWAYS"

  - `serial_number` (string,null)
    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` (object,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)

  - `_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.

  - `_links.authorizations` (object)

  - `_links.authorizations.href` (string)

  - `_links.merchant` (object)
    Link to the Merhcant resource that was used in the request.

  - `_links.self` (object)
    Link to the resource that was used in the request.

  - `_links.transfers` (object)

## Response 400 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 422 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.