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 support to handle retry requests via /v1/terminal/sessions/{id}/retry endpoint
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:
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:
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.

​
Troubleshooting

​
Common Issues and Solutions

Problem: The EDC (Electronic Data Capture) machine becomes unresponsive or stops processing transactions.Solution:
  1. Restart the EDC machine by holding the power button and selecting “Restart”
  2. Wait for the device to fully boot up and reconnect
  3. Verify the terminal is back online using the connection monitoring features
Always ensure the EDC is properly restarted before attempting new transactions to avoid data corruption.
Problem: Unexpected behaviors or unauthorized access to terminal functions.Solution:
  1. Ensure all transactions are initiated only through the app
  2. Contact the Xendit EDC team to enable POS-only mode for your Terminal IDs
  3. Configure terminal settings to disable manual transaction entry
POS-only mode prevents manual transaction entry and ensures all operations go through your application.
Problem: EDC fails to send transaction results to the app after payment completion.Solution:
  1. Query the Payment Session using the Terminal API to retrieve the latest status
  2. Check network connectivity between the EDC and your application
  3. Verify the callback URL configuration in your payment session
  4. Implement retry logic for failed status updates
Problem: Transaction appears stuck or you don’t receive a callback after the terminal prints a receipt, indicating the transaction may be incomplete.
This troubleshooting section applies only to BRI terminals.
Solution: Call the Terminal API retry endpoint /v1/terminal/sessions/{id}/retry to request the app check the transaction status and redo the transaction if it’s incomplete.
The retry endpoint instructs the app to verify the current transaction status with the terminal and automatically redo the transaction if it’s found to be incomplete.
Use this retry mechanism when you see a receipt printed but haven’t received a callback, as it may indicate the transaction didn’t complete successfully on the terminal side.
Problem: Unable to establish or maintain connection with terminal devices.Solutions:
  • Check network connectivity: Ensure both devices are on the same network
  • Verify IP addresses: Confirm terminal IP addresses are correct and accessible
  • Firewall settings: Check if firewall is blocking the connection ports
  • Terminal status: Ensure the terminal is powered on and in ready state
  • App initialization: Verify client key and terminal configuration
Use the connection monitoring features to diagnose specific connection issues.

​
Finding Terminal Information

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.