POS Emulator

POS Emulator

For testing purposes, we have created a POS emulator that works on Windows, Mac and Linux. It allows integrating with POS service without the need to run an actual device.

VersionDateDownload
1.4.02025-11-26pos-emulator-v1-26-11-2025.zip
1.3.02024-10-16pos-emulator-v1-16-10-2024.zip
1.2.02024-09-05pos-emulator-v1-05-09-2024.zip
1.0.02024-05-28pos-emulator-v1-22-05-2024.zip
POS Emulator Changelog
  • 1.4.0: Added new command line argument --iris that converts the transaction to an IRIS payment after the initiation.
  • 1.3.0: Added preloaded transactions capabilities. New configuration options preloadMenu and apiUrl, both are mandatory in order for the preload menu to work correctly.
  • 1.2.0: Added refund and void initiation capabilities
  • 1.0.0: Initial emulator version

Configure the Emulator

  1. Download and Extract: After downloading the desired for you, emulator version, extract the contents to a directory of your choice

  2. Open config.yml : Navigate to the extracted directory and locate the config.yml file.

  3. Edit Configuration: Open config.yml in your preferred text editor and update the following fields, with the credentials provided during terminal onboarding:

    • Listener Url
    • Listener Port
    • Terminal ID (TID)
    • Merchant ID (MID)
    • Authentication Token
    • Preload Menu (Optional)
    • Api URL (Optional, mandatory only when the preload menu is enabled)
    • Save the file after making the necessary changes

💡 Tip: Transactions with an amount equal to the failAmount specified in config.yml will result in a FAILED status. To ensure consistent simulation behavior, it is recommended to keep the failAmount parameter unchanged.

  1. Launch the Emulator

    • Windows: Execute the emulator_windows.exe file by double-clicking it.
    • MacOS:
      • Open Terminal.
      • Navigate to the directory containing the emulator executable (cd path/to/emulator_folder).
      • Change file permissions to executable using chmod +x pos-emulator-mac-amd-64
      • Run the command ./pos-emulator-mac-amd-64 to launch the emulator.
    • Linux:
      • Open Terminal.
      • Navigate to the directory containing the emulator executable.
      • Change file permissions to executable using chmod +x pos-emulator-linux-amd-64
      • Run the command ./pos-emulator-linux-amd-64 to launch the emulator.

  2. Canceled Transactions

    To emulate cancelled from the user or timed out transactions call the emulator with the --canceled argument

    ./pos-emulator-{os}-amd-64 --canceled

  3. Preloaded Transactions

    In order to enable the preloaded transactions functionality the following config settings must be added to config.yaml:

    • preloadMenu: true
    • apiUrl: "https://pos-api.url"

    Tip: We will provide you with the correct apiUrl value via email.

    Upon executing the pos emulator you will be prompt with the following message:

    Do you want to complete a preloaded transaction [y/N]:

    The default answer is 'No'. If you enter 'Y' or 'y', the emulator will display a numbered list of the preloaded transactions for this terminal (up to 50 transactions). The user will then be prompted to enter the number of the desired transaction they wishes to complete or 0 if they want to exit the preload menu.

  4. IRIS transactions

    To make an IRIS transaction add the --iris flag when calling the command. For example:

    ./pos-emulator-{os}-amd-64 --iris

    Prerequisites:

    • apiUrl: "https://pos-api.url" Add it in config.yaml in order for the iris transaction to work correctly

    When the initiation finishes, it will output to the console a URL that you must follow. This URL is DIAS' emulator.

    Instructions:

    • Successful:
      • In Local Instrument select INST
      • In Debtor IBAN select any option
      • The Debtor name is not needed; you can leave the default value.
      • Press the Confirm transaction button
    • Failed:
      • Press the Cancel transaction button

    Warning: DIAS emulator might display an error on the result page. This is expected behavior - the transaction status has still been updated correctly.

    After a few seconds you will see in the pos emulator's output the IRIS message and the pos emulator will respond with the IRISACK message, this means the transaction was completed successfully.

API Reference Â