Skip to main content

​
Terminal Gateway App Configuration

The Terminal Gateway app helps developers integrate their application with Xendit supported terminal devices. Configure connection types, manage devices, and monitor terminal status through an intuitive interface.
This app works alongside the Terminal API to provide complete in-person payment functionality. You’ll use the Terminal API to create payment sessions and this app to manage terminal device connections.

​
Version information

What’s new:
  • Fixed the NTT payment method value to ensure correct provider mapping
  • Updated the BRI payment flow to validate transaction data before performing terminal actions
  • Added timeout configuration for card and QR transactions to control operation windows
  • Added retry logic that leverages the Terminal API for more resilient recovery
What’s new:
  • Added support for multiple concurrent device connections so you can orchestrate simultaneous sessions across different terminals
  • [BRI] Fixed status value handling in void and cancel API responses for improved transaction status accuracy
  • Enhanced the Android app lifecycle with a splash screen, notification handling, and provider app launcher support for a smoother user experience
  • Fixed client-to-client API calls and the associated request queue to prevent stalled commands
New features and improvements:
  • Added transaction timeout configuration with UI support and validation
  • Introduced command ID handling for settlement operations
  • Enhanced retry logic with configurable attempt counts
  • Improved error handling and logging throughout the gateway service
  • In-app version update
  • Renamed to Gateway with updated icons
Bug fixes and improvements:
  • Fix data mapping for terminal responses
  • Hide device’s restart button when connection mode is C2C
  • Fix “restart service” button behavior on C2C mode
  • [BRI] Enhanced status verification after transaction timeout for improved reliability
Bug fixes and improvements:
  • Fix UI issue
  • Fix date time parser issue
  • Fix test flag toggle not showing correct state on app open
Update UI/UX for improved user experience and interface design.
Remove timezone pinning for the BRI terminal. Fix an issue where the app executes the same command after a transaction completes.
Terminal Gateway is the companion SDK to In-Person Payments Terminal API.
The app follows semantic versioning. Breaking changes will bump the major version number.

​
Download the app

Choose your operating system to download the Terminal Gateway app installer:

macOS (.dmg)

Download the macOS installer (v1.6.0)
SHA256: f35520476b0cabccecc2fb4912c081168c6c1070018394cacd823dfd018cfd95

Windows (.msi)

Download the Windows installer (v1.6.0)
SHA256: efceec75dd27e3d8d74b9b1fa134d6cb2e52ff972b1f29f970d3d1f1dd30b1bf

Android (.apk)

Download the Android APK (v1.6.0)
SHA256: d1839cbc3c98979c220f87a688672d4bac6a9567821b141e52c332281c638c6d

​
Getting Started

Before starting, you’ll need a terminal CLIENT_KEY from the Xendit In-Person Payments team and add a device.
Keep your client key secure and never share it with unauthorized parties. Use test keys for development and production keys only for live environments.
1

Enter Client Key

When the app opens for the first time, a modal will appear. Enter your testing CLIENT_KEY in the “Test API Key” field and click “Save”.
Entering client key in Terminal Gateway app modal
2

Add Your First Device

Click ”+ Add Your First Device” to link a terminal device.
Adding first device in Terminal Gateway app
3

Configure Device

Fill in Terminal ID and IP Address, and click “Add Device” button.
Filling in terminal ID and IP address configuration
4

Test Connection

The app will test the connection with the added device and run the service. The app is now accepting commands.
Terminal Gateway app testing connection with device
Your Terminal Gateway app is now ready to accept commands from your POS system.

​
Connection Types

The Terminal Gateway app supports two connection modes for different integration scenarios:
  • Host-to-Host (Default)
  • Client-to-Client
Recommended for most use cases - The app runs a host-to-host service that manages your terminal fleet centrally.
1

Default Configuration

The app automatically runs in host-to-host mode when first launched.
2

Manage Terminals

Add and manage multiple terminal devices through the app interface.
3

Centralized Control

All terminal communications are handled through the app’s centralized service.
Host-to-host mode is ideal for managing multiple terminals and provides easier fleet management.

​
Environment Configuration

Configure the app for different environments based on your development and production needs:
  • Test Mode (Default)
  • Production Mode
For development and testing - Use test client keys and sandbox environment.
1

Initial Setup

When the app opens for the first time, enter your testing CLIENT_KEY in the “Test API Key” field.
2

Test Transactions

All transactions are processed in test mode and won’t affect real payment data.
Test mode is enabled by default and uses the test environment for all transactions.

​
Transaction Timeout

Use transaction timeouts to auto-cancel in the app and reissue transactions when a terminal does not respond in time. You can set independent limits for card and QR flows.
1

Open Settings

Click the settings icon in the top-right corner of the app home screen.
2

Select Transaction Timeout

In Settings, choose Transaction Timeout under the Network section.
Gateway app settings screen showing the Transaction Timeout option under Network
3

Configure Card and QR timeouts

  • Card Timeout (minutes) — maximum time the terminal has to complete a card transaction before the app auto-cancels and retries the transaction.
  • QR Timeout (minutes) — maximum time for QR transactions before the app auto-cancels and retries the transaction.
4

Save changes

Click Save Changes to apply the new timeouts.

​
Device Status Monitoring

Each device in the terminal list displays a status indicator that changes color based on its current state. Monitor these indicators to ensure your terminal fleet is operating correctly.

​
Status Indicators

StatusColorDescription
Unreachable/OfflineRedEDC terminal is unreachable or offline due to incorrect IP address, network issues, or missing EDC configuration
ProcessingYellowA transaction is currently in progress on the EDC terminal
OnlineGreenEDC terminal is online, connected, and ready for transactions
DisabledGreyEDC terminal is disabled and not available for transactions

​
Troubleshooting Status Issues

Problem: Terminal shows red status indicating it cannot be reached or is offline.Solutions:
  • Verify the terminal IP address is correct and accessible
  • Check network connectivity between the app and terminal
  • Ensure the terminal is powered on and properly configured
  • Verify firewall settings aren’t blocking the connection
    Red status terminals cannot process transactions and require immediate attention.
Problem: Terminal shows grey status indicating it’s disabled.Solutions:
  • Check if the terminal has been manually disabled in the app
  • Verify terminal configuration and settings
  • Restart the terminal connection if needed
  • Contact support if the issue persists
    Disabled terminals are intentionally unavailable and won’t process transactions.
Problem: Terminal shows yellow status indicating a transaction is in progress or appears stuck.Solutions:
  • Verify the terminal and POS are properly connected to the network
  • Check if the current transaction is still awaiting card input or PIN
  • Confirm whether the POS has already received a callback/response
  • Review app logs for timeouts or error messages during processing
    Yellow status is normal while a transaction is actively processing.
Context: Terminal shows green status indicating it is online and ready.What this means:
  • The device is connected and reachable by the app
  • No transaction is currently in progress
  • The terminal can accept new commands
If you still encounter issues:
  • Confirm the POS is sending commands to the correct terminal
  • Verify API credentials and environment (test vs production)
  • Check recent logs for command errors or rejected requests
    Green status indicates the terminal is healthy and ready to use.
Monitor device status indicators regularly to ensure your terminal fleet is operating correctly. Red or grey statuses may require immediate attention.

​
Finding Terminal Information

  • BRI Terminals
  • NTT Terminals
1

Find Terminal ID (TID)

Open the BRI FMS app on the terminal device and locate the Terminal ID in the device information section.
BRI terminal showing Terminal ID in FMS app
2

Find IP Address

Open the ECRLink app on the terminal and check the network settings for the IP address.
BRI terminal showing IP address in ECRLink app
Screenshots and UI layouts may vary by firmware or app version. Refer to the latest vendor documentation if the interface differs from these instructions.