Point-of-sale icon

Schedule terminal actions

Use our Management API to schedule actions on terminals, such as (un)installing Android apps and certificates.

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 us, 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.

API key and roles

To authenticate your requests to Management API, you need to have an API credential with an API key and the following roles:

  • Management API—Terminal actions read
  • Management API—Terminal actions read and write
  • Management API—Terminal settings read
  • POS Terminal Management API

The last two roles above are required for getting the IDs of the terminals that you want to apply an action to.

If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.

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 you keep your terminals turned on and connected to the network overnight.

In the case of Android terminal actions, the terminal doesn't 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 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 you know the ID of your company. If you don't know this ID, make a GET /companies request.

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

    Get a list of Android apps that have been uploaded, by making a GET /companies/{companyId}/androidApps request.
    These are the query parameters to filter the paginated response:

    • pageNumber: returns the apps shown on the specified page.
    • pageSize: the number of apps to have on a page. The default is 20, the maximum is 100.

    The response returns the following details of all apps that have been uploaded to Adyen and are in the ready status:

    Parameter Description
    id The unique, Adyen-generated identifier of the app. Starts with ANDA.
    packageName The package name of the app. For example, com.your_company.posapp.
    versionCode The internal version number of the app.
    description The description that was entered in the Customer Area when uploading the app. The description is not shown on the terminal.
    label The app name that is shown on the terminal.
    versionName The app version number that is shown on the terminal.
    status The status of the app: ready.
  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 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 a new app version and remove an old app version, 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 -white_check_mark- 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 don't 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+01:00
    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 -white_check_mark- 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