Guides

Registering and deregistering terminals

After you have configured a terminal that provides a registration code (see Configuring your terminal for NMI), you must register it with the appropriate gateway before you can use the terminal to process payments.

📘

Note

Unlike the terminal pairing process where codes are provided by the Nexio API to be entered into a terminal, registration codes come from the terminal and are provided to the Nexio API.

This tutorial contains two main sections:

Registering the terminal

In order to register your terminal for use with Nexio, you must have completed setup.

Depending on your integration, you can register a terminal through one of the following options:

Register with the iframe

If your integration uses Nexio's retail iframe, the registration workflow will be available to users by default. If a merchant has been configured with a gateway that supports terminals (whether pairing-based, registration-based, or both), the iframe allows users to add a terminal.

After a terminal is registered, the retail iframe allows users to select the terminal for processing a payment.

You can see the retail iframe workflow in action in the Nexio iframe tester.

Complete the following steps to register the terminal:

  1. Make sure that the terminal is powered on and connected to a Wi-Fi network.

  2. Refer to the Customizing the retail iframe topic for information about customizing and prefilling the iframe.

  3. Authenticate with the retail iframe through either of the following options:

  4. After the retail iframe loads, go to Payment Method and select Card (terminal) from the list.

  5. Select the Add Terminal option at the bottom of the iframe.
    If your merchant account configuration supports both registration-based and pairing-based terminals, a dialog displays where you select which type of terminal you want to support. Select the registration option to move to the next dialog.
    Otherwise, if the configuration only supports registration-based terminals, the next dialog displays.
    (If the configuration only supports pairing-based terminals, stop following these steps and go to the Pairing the terminal content in the "Configuring your terminal for USAePay" tutorial.)

  6. In the Enter terminal registration info dialog, type the following:

    1. Terminal Name - This value is optional. It is an alphanumeric (up to 20 characters) value that acts as a nickname for the terminal. The system ignores special characters. This terminal name is a helpful identifier when a single merchant ID (Processing Account) has multiple configured terminals.
    2. Registration Code - This value displays on the terminal. Locate the value and type it in this field exactly as it appears.
      To test the registration process, use T00001 to model a successful registration or T00002 for a failed registration.

  7. Click Submit to save the information.

  8. If registration completes successfully, the dialog title changes to Successfully registered terminal. Click Continue to Payment to proceed.
    If registration fails, the system receives an error message and the dialog reloads.

Now that you have registered your terminal, you can process a transaction by following steps in Processing a transaction with a terminal.

Register with the API

This registration workflow allows integrated users the most control over the merchant experience by keeping merchant users within the software (no need to access a gateway user interface or contact Nexio support). However, this may increase the effort required to integrate.

Complete the following steps to register the terminal:

  1. Send a POST request to the Register terminal endpoint. A successful request returns a response that includes a terminalId. To test the registration process, for the terminalRegistrationCode value use T00001 to model a successful registration or T00002 for a failed registration.

    curl -X POST https://api.nexiopaysandbox.com/pay/v3/registerTerminal \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "merchantId": "100039",
    "terminalRegistrationCode": "T00001",
    "terminalName": "FrontDesk1"
}'

    {
  "terminalId": "eyJtZXJjaGFudElkIjoiMzAxNBUxIiwiZ2F0ZXdheUxhYmVsIjoiLXNrOi4uLldqNUIsY2Nwcm9jZXNzb3JhIiwidGVybWluYWwiOnsiaWQiOiJmYTMzMmQ0Zi02ZjQ2LTQ0YmYtOWEyOC0wMDAwMDAwMDAwMDAifX0=",
  "terminalSerialNumber": "103070PT110315",
  "terminalRegistrationStatus": "registered",
  "terminalName": "FrontDesk1",
  "deviceId": "2205dffc-6bfa-4bd8-aa2f-000000000000"
}

  2. Send a GET request to the View terminal list endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID.

    curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'

    [
  {
    "merchantId": "100039",
    "merchantName": "Merchant",
    "gatewayName": "nmi",
    "gatewayType": 20,
    "gatewayLabel": "[label]",
    "terminalName": "FrontDesk1",
    "terminalSerialNumber": "103070PT110315",
    "terminalStatus": "connected",
    "deviceId": "2205dffc-6bfa-4bd8-aa2f-000000000000",
    "terminalId": "eyJtZXJjaGFudElkIjoiMzAxNBUxIiwiZ2F0ZXdheUxhYmVsIjoiLXNrOi4uLldqNUIsY2Nwcm9jZXNzb3JhIiwidGVybWluYWwiOnsiaWQiOiJmYTMzMmQ0Zi02ZjQ2LTQ0YmYtOWEyOC0wMDAwMDAwMDAwMDAifX0="
  }
]

    Confirm that the newly registered terminal is included the response and the terminalStatus is connected.


After the terminal is registered, you can use any of the options for Processing a transaction with a terminal.

Register within the gateway UI

This registration workflow bypasses the need to use Nexio’s API or the iframe. A merchant user (or Nexio support) completes the registration directly within the gateway's user interface (UI). This requires that person to have access to the terminal device.

See the documentation for the gateway for information on how to register the terminal through the UI.

After the terminal is registered, use the View terminal list endpoint to get its terminalId. Then, use any of the options for Processing a transaction with a terminal.

Deregistering the terminal

In a situation such as when the terminal needs to be used with a different gateway account, the terminal must first be deregistered from the current gateway account. Deregistering a terminal also removes it from the results of the View terminal list endpoint and the list of terminals in the retail iframe.

Depending on your integration, you can deregister a terminal through one of the following options:

Deregister with the API

This method offers the most control over the merchant user experience by keeping the user within the integrated software workflow.

Complete the following steps to deregister the terminal:

  1. Send a POST request to the Deregister terminal endpoint using the device's terminalId. 

    curl -X POST https://api.nexiopaysandbox.com/pay/v3/deregisterTerminal \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
}'

    {
  "terminalRegistrationStatus": "deregistered"
}

    Confirm that the terminalRegistrationStatus in the response is deregistered.

  2. Send a GET request to the View terminal list endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID.

    curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'

    [
  {
    "merchantId": "100039",
    "merchantName": "Merchant",
    "gatewayName": "nmi",
    "gatewayType": 20,
    "gatewayLabel": "[label]",
    "terminalName": "FrontDesk2",
    "terminalSerialNumber": "104070PT110316",
    "terminalStatus": "connected",
    "deviceId": "2305dffc-6bfa-4bd8-aa2f-000000000000",
    "terminalId": "eyStZXJjaGFudElkIjoiMzAxNBUxIiwiZ2F0ZXdheUxhYmVsIjoiLXNrOi4uLldqNUIsY2Nwcm9jZXNzb3JhIiwidGVybWluYWwiOnsiaWQiOiJmYTMzMmQ0Zi02ZjQ2LTQ0YmYtOWEyOC0wMDAwMDAwMDAwMDAifX0="
  }
]

    Confirm that the newly deregistered terminal is not included the response.

Deregister within the gateway UI

This workflow bypasses the need to use Nexio's API. However, this method requires either a merchant user or Nexio support to access the gateway UI to complete the deregistration..

Updated 5 days ago