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

API Reference Â