Pair a new terminal

A terminal must be paired using the API to initiate transactions on it.

This process flow diagram illustrates the API calls required to pair a terminal and retrieve connection details to enter into the terminal.

1. Tell us about your terminal

2. A resource URL is returned which can be polled for the connection status.

3. A unique IP address, port and path will be returned.

4. Enter the ECR details into your terminal

5. Terminal status should update to 'Connected'. Your terminal is now paired and ready to accept transactions.

Telling us about your terminal

To initiate the pairing process you must POST a PairDeviceRequest object to the PairTerminal endpoint, you will then receive a response containing a ResourceResponse object containing the information that you will need to proceed.

The example below shows the code required to initiate the pairing process.

The initial response from the Post to the Terminal endpoint will be:

The resource ID is the identifier for the terminal which has been created in our system, you can use this (or the terminal TID) when querying for the status of the terminal.
The Resource URL is the URL at which you can find information about this terminal, including the IP address and port number of the ECR that it has been assigned to.

Retrieve connection details & update your device

Once you have set your terminal up in the system you will need to update your device with details of the ECR that it will be connecting to.
In order to do this you will make a GET request to the ResourceUrl of the terminal, this will give you an object with the properties shown below.

You should poll this endpoint until the state changes from "Provisioning" to "AwaitingPairing" this indicates that the ECR has been set up and is now awaiting connections from your terminal.

You should now follow the process of manually setting your terminal to ECR Mode and updating the IP Address & Port Number.

You may wish to continue polling the Get Terminal endpoint during the remainder of the pairing process in order to check the state correctly changes to "Connected", in the event that something goes wrong with the process the state property will indicate what the problem is.

Once the state of your terminal is showing as "Connected" the pairing process is complete.

Code Example

In the sample below we will

(Please note for the A920/ A920 Pro - the Terminal ID or 'TID' field is actually the Serial Number on the device. Please use the Serial Number when there is any mention of a Terminal ID or 'TID'.)

1.  Create an instance of an http client and pass in the jwt token

2.  POST terminal data to the terminal endpoint

3.  Poll the API at 500ms intervals until the terminal state is AwaitingPairing

4.  Display the terminals assigned IP address and port number to the user

5.  Poll the API at 500ms intervals until the terminal state indicates pairing is complete