Schedule terminal actions

Terminal actions are operations that need to be carried out on payment terminals, and that can be planned for a certain date and time. Most of those actions are planned by Adyen, like updating to a release, or obtaining logs. Some actions can also be planned by you.

Here we describe how you can use our Management API to automate planning terminal actions on Android payment terminals.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

When planned actions take effect

Terminal actions are changes in the configuration of the terminal. The terminal receives configuration changes when it makes a maintenance call and implements the changes when it reboots at the restart hour (at 06:00 AM by default).
To ensure this process succeeds, we recommend that you keep your terminals turned on and connected to the network overnight.

In the case of Android terminal actions, the terminal does not wait until the restart hour.

• If you planned the Android action without a date and time, the action is implemented with the next maintenance call. If WebSockets are enabled, the action is implemented immediately.
• If you planned the Android action for a specific date and time, the action is implemented with the first maintenance call after that date/time in the time zone of the terminal. If WebSockets are enabled, the action is implemented at the exact date and time that you specified.

If the action involves an Android app that is already installed on the terminal and that happens to be open at the time of the action, the app closes.

Android terminal actions

Android terminal actions are related to the deployment of apps that you want to run on your Android terminals. For example, a POS app. To run such an app, you need to install it on the terminal. Maybe you also need to remove an old version that you no longer want to use.

Some apps need a digital certificate. For example, a certificate to protect network communications between a POS app and the back end of that app. Such a certificate needs to be installed on the terminal, and replaced with a new one before the validity period of the certificate expires.

To sum up, Android terminal actions you can plan are:

• Install a new app or app version.
• Uninstall an old app or app version.
• Install a new certificate.
• Uninstall an expired certificate.

These actions are part of a larger process where you:

1. Make sure that the app meets the requirements.
2. Upload the app in your Customer Area. We then sign the app and convert it so that the terminal can handle the app.
3. If the app requires a certificate, upload the certificate as well, so that we can sign it.
4. Plan terminal actions to install or uninstall apps and certificates. You can plan actions in your Customer Area, but here we describe how to plan actions by making API calls to:
   1. Get the IDs of the apps or certificates that have been uploaded.
   2. Get the IDs of the terminals that you want to apply the action to.
   3. Plan an Android terminal action.

Step 1: Get Android app and certificate IDs

When planning an Android terminal action, you need to provide the ID of the Android app or certificate you want to install or uninstall. To get those IDs, check which apps and certificates have been uploaded:

1. Make sure that you know the ID of your company. If you do not know this ID, make a GET /companies request.

2. Check what Android apps and optionally what Android certificates are available.

3. From the response, save the id of the Android app or certificate that you want to install or uninstall.

Step 2: Get terminal IDs

When planning an Android terminal action, you need to provide the IDs of the terminals that you want to apply an action to. To create a list of terminals:

1. Make a GET /terminals request using query parameters to restrict the list to terminals that match specific conditions. You can specify multiple values for a single query parameter like this: /terminals?countryCodes=NL,FR.

   These are the query parameters to filter the paginated response:

   Query parameter	Result
   searchQuery	Returns terminals with an ID that contains the specified string. If you use this query parameter, other query parameters are ignored.
   countries	Returns terminals located in the countries/regions specified by their two-letter country code in ISO 3166-1 alpha-2 format.
   merchantIds	Returns terminals that belong to the merchant accounts specified by their unique ID. For a list of merchant account IDs, make a GET request to /companies/{companyId}/merchants.
   storeIds	Returns terminals that are assigned to the stores specified by their unique store ID. For a list of store IDs, make a GET /stores request.
   brandModels	Returns terminals of the specified models in the format brand.model. For example, Castles.S1F2. For a list of brand models, make a GET /terminalModels request and use the id from the response.
   pageNumber	Returns the terminals shown on the specified page.
   pageSize	The number of terminals to have on a page. The default is 20, the maximum is 100.

   The following example shows how to create a list of all S1E and S1F2 Android terminals for a specific merchant account.

   For each terminal, notice in the response:

   • id: the unique terminal ID.
   • status: indicates when the terminal was last online, whether the terminal is being reassigned, or whether the terminal is turned off. If the terminal was last online more that a week ago, it is also shown as turned off.
   • assigned: true indicates the terminal is assigned to a store, or to a merchant account representing a store. false indicates the terminal is in inventory.

2. Extract the unique terminal IDs from the response.

Step 3: Schedule an Android terminal action

When planning terminal actions, be aware of the following restrictions:

• You can schedule one action at a time. For example, to install two different apps you have to make two API requests.
• The maximum number of terminals in a request is 100. For example, to apply an action to 250 terminals, you have to divide the terminals over three API requests.
• If there is an error with one or more terminal IDs in the request, the action is scheduled for none of the terminals. You need to fix the error and try again.

To plan an Android terminal action:

1. Make a POST /terminals/scheduleActions request, specifying:

   Parameter	Required	Type	Description
   terminalIds		String array	A list of unique IDs of the terminals to apply the action to. You can extract the IDs from the GET /terminals response. Maximum length: 100 IDs.
   storeId		String	The unique ID of the store that the terminals are assigned to. If you do not know this ID, make a GET request to /stores. The request fails if the terminalIds do not belong to this store.
   scheduledAt		String	The date and time when the action should happen. Format: RFC 3339, but without the Z before the time offset. For example, 2021-11-15T12:16:21+0100 The terminal installs or removes the app with the first maintenance call after the specified date and time in the time zone of the terminal. An empty value causes the action to happen as soon as possible: at the next maintenance call.
   actionDetails		String object	This is where you specify the app or certificate ID and the action. For an Android app action, this object must contain: appId: the unique identifier of the app. type: the type of action. Possible values: InstallAndroidApp or UninstallAndroidApp. For an Android certificate action, this object must contain: certificateId: the unique identifier of the certificate. type: the type of action. Allowed values: InstallAndroidCertificate or UninstallAndroidCertificate

   The following examples show how to install an app, and how to uninstall a certificate.

   We first validate the list of terminals. If the list is correct, we try to send the action details to the terminals.

2. If you receive a 422 validation error response, check the invalidFields array for the details, fix the errors, and send the planning request again.

   For each error, the InvalidField.message explains what is wrong:

   • InvalidTerminal: the terminal ID is incorrect.
   • CompanyHasNoPermissionToThisTerminal: the terminal belongs to a company that the API credential that was used for the request doesn't have access to.
   • TerminalIsNotFromStore: the terminal is not assigned to the store that was specified in the request.

   The following example shows validating the list of terminals failed because two of the three terminal IDs are incorrect.

3. If there are no errors with the validation of the terminal IDs, check whether the action was planned:

   • totalScheduled: The number of terminals for which planning the action succeeded. This doesn't mean the action has happened yet.
   • totalErrors: The number of terminals for which planning the action failed. For example, due to connection problems.
   • items: A list with the unique terminalId and the unique action id for each terminal that the action was scheduled for. The action id starts with TRAC. You can use it to retrieve the details of an action. For example, whether the action was carried out successfully.

Step 4 (optional): Get terminal action details

After the terminal action is planned, you can retrieve the details of that action to check if the action has been carried out. This is only possible for terminal actions that you planned, not for actions that were planned by us.

To get details of a terminal action:

1. Make a GET /companies/{companyId}/terminalActions/{actionId} request specifying the id of the planned terminal action from the /terminals/scheduleActions response.

2. In the response, see the status to learn if the action has been carried out.
   These are the full response details:

   Response parameter	Result
   actionType	The type of terminal action: InstallAndroidApp, UninstallAndroidApp, InstallAndroidCertificate, or UninstallAndroidCertificate.
   config	Technical information about the terminal action.
   confirmedAt	The date and time when the terminal returns the status of the action. For example, whether the action succeeded, failed, or was cancelled.
   id	The unique identifier of the terminal action.
   result	The result message in case the status of the action is successful, failed, or cancelled. For example, Version apk0 installed or Failed.
   scheduledAt	The date and time when you scheduled the action to happen.
   status	The status of the terminal action: pending, successful, failed, or cancelled.
   terminalId	The unique identifier of the terminal that the action applies to.

See also