Skip to main content

​
Terminal H2H SDK for iOS (Swift)

The Terminal H2H SDK for iOS enables you to integrate secure payment processing directly into your iOS applications. Connect to physical payment terminals and process transactions seamlessly using our comprehensive Swift SDK.
This SDK works alongside the Terminal API to provide a complete in-person payment solution. You’ll use the Terminal API to create payment sessions and the Terminal H2H SDK to interact with physical payment devices.

​
Version information

What’s new:
  • Renamed class name TerminalGateway to TerminalH2H for better consistency
Breaking Change: Class name changed from TerminalGateway to TerminalH2H. Update your imports and references accordingly.
What’s new:
  • Fixed NTT payment method value mapping to ensure correct provider selection
  • Updated BRI payment flow to validate transaction data before executing terminal actions
  • Added timeout configuration for card and QR transactions to auto-cancel and retry stalled requests
  • Added support to handle retry requests via /v1/terminal/sessions/{id}/retry endpoint
What’s new:
  • Added support for multiple concurrent device connections, enabling simultaneous transactions across different terminals
  • [BRI] Fixed status value handling in void and cancel API responses for improved transaction status accuracy
What’s new:
  • Introduced command ID handling for settlement operations
  • Enhanced retry logic with configurable attempt counts
  • Improved error handling and logging throughout the gateway service
Bug fixes and improvements:
  • Fix data mapping for terminal responses
  • [BRI] Enhanced status verification after transaction timeout for improved reliability
XenTerminal is the companion SDK to In-Person Payment Sessions API. This version provides core functionality for connecting to payment terminals and processing transactions.
The SDK follows semantic versioning. Breaking changes will bump the major version number.

​
Download

Download the Terminal H2H iOS SDK:

iOS SDK (v1.0.0)

Download the complete iOS SDK package including TerminalH2H.xcframework and documentation
SHA256: 61a97854a65501d0c1c14dc7fe94005cd6c0d72b35ee6157ec5a65c74b52e8b7

​
Installation

Install the Terminal SDK by adding it as a framework in Xcode:
1

Extract framework

Extract the framework zip file in your project directory.
Extracting framework zip file in Finder
2

Add framework to project

In Xcode, open your project and choose File → Add Package Dependencies… to start the package flow.
Opening the Add Package Dependencies menu in Xcode
3

Import framework

  1. Click Add Local… when prompted.
  2. Browse to the extracted framework zip/location and select the package manifest.
  3. Ensure the correct target is selected, then click Add Package to finish.
Choosing Add Local during the package dependency flow
Locating the extracted framework files
Selecting the correct target before adding the package
4

Configure build settings

Go to “Build Settings” and make the following changes:
  • Search for “ENABLE_USER_SCRIPT_SANDBOXING” and set it to “NO”
  • Search for “Other Linker Flags” and add “-lsqlite3”
Setting ENABLE_USER_SCRIPT_SANDBOXING to NO in Xcode Build Settings
Adding -lsqlite3 to Other Linker Flags in Xcode Build Settings

​
Getting Started

Before starting, you’ll need an In-Person Payment CLIENT_KEY from the Xendit In-Person Payment team. You will also need the terminal IP address.
Terminal H2H requires physical payment devices to function. Contact the Xendit team to obtain compatible terminal devices and configuration details.

​
Step 1: Initialize SDK

Import the SDK module and call TerminalApp.shared.initialize from your application entry point:
AppDelegate.swift
import TerminalH2H

TerminalApp.shared.initialize(
  clientKey: TEST_CLIENT_KEY,
  mode: TerminalMode.integration // switch to TerminalMode.live for production builds
)
The SDK supports two modes:
Use TerminalMode.integration for development and testing with physical terminals. Transactions are sent to Test Mode on the Xendit Dashboard.

​
Step 2: Add Terminal Providers

Add the specific terminal providers you need for your integration:
For Share Commerce (SHC), Cashup, and Atom terminals, you do not need to add a Terminal H2H provider. Those devices run terminal logic through the Gateway app installed on the hardware. If the app is missing, install it from the Gateway download page or contact inpersonpayments@xendit.co for help.
// Add BRI provider for Indonesian terminals
TerminalH2H.shared.addProvider(provider: TerminalBRI.shared)
BRI provider supports timeout configuration for card and QR transactions, and provides enhanced transaction retry capabilities.
After adding providers, they will be available for use when registering terminal devices in the next step.

​
Step 3: Register Terminal Device

Create terminal device entries using TerminalDevice.companion.create and register them with the gateway: 
let devices = [
  TerminalDevice.companion.create(id: "BRI12345", ipAddress: "192.168.1.10"),
  TerminalDevice.companion.create(id: "BRI67890", ipAddress: "192.168.1.11")
]

TerminalH2H.shared.registerDevices(
  devices: devices,
  restart: true // restart to apply the refreshed device list immediately
)
For detailed instructions on finding Terminal ID and IP address for different terminal providers, see our Finding Terminal Information guide.

​
Step 4: Calling Terminal API

With Terminal H2H SDK configured, you can now process payments using the Terminal API. The SDK handles communication with physical terminals through the local gateway service. 
# Example: Create a payment session
curl -X POST 'https://terminal-dev.xendit.co/v1/terminal/sessions' \
  -u 'API_KEY:' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-key: unique-session-123' \
  -d '{
    "terminal_id": "TERMINAL_ID",
    "amount": 10000,
    "currency": "IDR",
    "external_id": "payment-123",
    "payment_method": "card"
  }'
For complete API documentation including request/response formats, error handling, and advanced features, see the Terminal API (H2H) documentation.
The Terminal H2H SDK automatically manages the connection to your registered terminal devices and handles communication protocols for different providers.
You’re now ready to process payments using the Terminal H2H SDK integrated with Terminal API.

​
Optional Methods

​
Set Operation Timeout

Configure the maximum allowed time for operations to complete before the service cancels and retries the transaction: 
TerminalH2H.shared.setOperationTimeout(minutes: 5) // default value is 5 minutes

// Set provider-specific timeouts
TerminalH2H.shared.setOperationTimeout(type: TimeoutType.card, minutes: 10)
TerminalH2H.shared.setOperationTimeout(type: TimeoutType.qr, minutes: 10)

​
Restart Terminal Connection

Manage and restart terminal service connections:
Call the method without parameters to restart all connections and tasks:
// This restarts all connections
TerminalH2H.shared.restart(terminalID: nil)

​
Observing Connection State

Monitor Terminal connection status using the observeEDCConnection method: 
let device = TerminalDevice.companion.create(id: "BRI12345", ipAddress: "192.168.1.10")

TerminalH2H.shared.observeConnection(device: device) { state in
  // Handle connection state transitions
}
The SDK handles the following connection states:
CodeDescription
connectedDevice connected to Terminal
disconnectedDevice disconnected to Terminal
unknownWhen no connection has been established yet
connectingDevice requesting connection to Terminal
connectingFailedDevice unable to connect with Terminal
unsupportedConnection not supported
unreachablePing failed; gateway marks device unreachable until it recovers

​
Observing Error State

Monitor Terminal error states using the observeError method: 
TerminalH2H.shared.observeError { device, error in
  // Use device?.id to correlate errors with specific terminals
}

​
Error Handling

​
Error Data Structure

All errors returned by the Terminal H2H SDK follow this structure: 
struct TerminalError {
    let code: ErrorCode
    let message: String
}

​
Error Codes Reference

Error CodeHTTP StatusDescription
INVALID_CREDENTIAL401Provided credentials are invalid or expired
INVALID_REQUEST400Request format or parameters are invalid
INTERNAL_SERVER_ERROR500Server-side error occurred during processing
UNKNOWN_ERROR-Unexpected error that does not map to a specific category
KEY_INVALID-1API key is invalid or not authorized
AUTHENTICATION_FAILED-21Terminal authentication failed - verify terminal ID and credentials
FAILED_TO_CONNECT-4Unable to establish connection to terminal
NOT_CONNECTED-3No active connection to any terminal device
TERMINAL_BUSY-6Terminal is processing another transaction
SEND_FAILED-2Failed to send data to the terminal device
UNSUPPORTED-5Operation or platform not supported
ENCRYPTION_FAILED-7Encryption key invalid or encryption process failed
DECLINED_BY_READERN/ACard or reader rejected the transaction; prompt customer to retry
PAYMENT_UNPAIDN/APayment still pending on terminal; confirm status before retrying
DUPLICATEDN/ADuplicate command detected; generate a new order ID before retrying
CANCELLEDN/AAction cancelled on the terminal or by the operator
TIMEOUTN/AOperation exceeded configured timeout window
NO_DATA_FOUNDN/ATerminal cannot find the referenced transaction data
TID_NOT_SETN/ATerminal ID is missing in the gateway configuration
TID_NOT_MATCHN/ATerminal ID does not match the registered device

​
Error Handling Best Practices

Implement comprehensive error handling for robust payment processing: 
func handleTerminalError(_ error: TerminalError?) {
  guard let error = error else { return }

  switch error.code {
  case ErrorCode.authenticationFailed:
    // Verify API key and <a href="#finding-terminal-information">terminal ID</a>
    print("Authentication failed: \(error.message)")
    // Show user-friendly message and retry with correct credentials
        
  case ErrorCode.terminalBusy:
    // Terminal is processing another transaction
    print("Terminal busy: \(error.message)")
    // Wait and retry after a delay
    retryAfterDelay(5.0) // 5 seconds
        
  case ErrorCode.failedToConnect, ErrorCode.notConnected:
    // Network connectivity issues
    print("Connection failed: \(error.message)")
    // Check network connection and terminal <a href="#finding-terminal-information">IP address</a>
    checkNetworkConnectivity()

  case ErrorCode.declinedByReader:
    // Terminal rejected the card tap/insert
    print("Declined by reader: \(error.message)")
    promptCustomerToRetry()

  case ErrorCode.paymentUnpaid:
    // Payment still pending on the terminal
    print("Payment unpaid: \(error.message)")
    confirmStatusWithBackend()

  case ErrorCode.timeout:
    // Gateway timed out while waiting for terminal response
    print("Command timeout: \(error.message)")
    TerminalH2H.shared.restart(terminalID: nil)

  case ErrorCode.duplicated:
    // Duplicate command detected by the gateway
    print("Duplicate command detected: \(error.message)")
    regenerateOrderID()
        
  case ErrorCode.keyInvalid, ErrorCode.invalidCredential:
    // Credential issues
    print("Invalid credentials: \(error.message)")
    // Rotate or refresh API credentials
    refreshCredentials()
        
  case ErrorCode.encryptionFailed:
    // Encryption key issues
    print("Encryption failed: \(error.message)")
    // Re-initialize SDK with correct encryption keys
    reinitializeSDK()

  case ErrorCode.cancelled:
    // Operator cancelled the command on the terminal
    print("Operation cancelled: \(error.message)")
    notifyCashier()
        
  default:
    // Log and escalate unknown errors
    print("Unknown error: \(error.message)")
    // Report to monitoring system
    reportError(error)
  }
}
Always implement retry logic for transient errors like TERMINAL_BUSY and FAILED_TO_CONNECT. Use exponential backoff to avoid overwhelming the terminal.

​
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 SDK
  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 SDK 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
// Example: Query payment session status
let paymentSession = terminalApi.getPaymentSession(sessionId)
switch paymentSession.status {
case PaymentStatus.completed:
    // Process successful payment
case PaymentStatus.failed:
    // Handle failed payment
case PaymentStatus.pending:
    // Payment still in progress
}
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 to request the app check the transaction status and redo the transaction if it’s incomplete:
// Retry transaction via Terminal API
let response = try await terminalApi.retrySession(sessionId: sessionId)
// The app will check transaction status and redo if incomplete
The retry endpoint /v1/terminal/sessions/{id}/retry 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
  • SDK 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.