Troubleshooting Guide
Use this guide when a payment flow does not behave as expected on a real terminal or during local terminal testing. It helps you identify whether the issue is in your H2H or C2C runtime flow and choose the right recovery action.This page focuses on operational troubleshooting for SDK and terminal runtime issues. For request validation, authentication, and simulation-specific API errors, see Errors & Simulations.
Before you troubleshoot
Confirm these basics before you retry a payment:- Identify your connection mode:
H2HorC2C - Confirm whether you are using simulation or a real terminal
- Verify the terminal shows
Online,Connected, orReady - Verify the
terminal_id, IP address, client key, and environment are correct - Check that your terminal, mobile device, and Gateway service are on the expected network
Troubleshooting matrix
Use this table to choose the next action quickly.| Case | Connection mode | What to check first | Recommended action |
|---|---|---|---|
| Terminal does not show a payment prompt | H2H | Terminal connection status, terminal registration, network connectivity, test vs live environment | Confirm the terminal is connected and registered, then restart the SDK or gateway connection if needed |
| Payment completed on terminal but your app received no final response | H2H | Payment Session status, callback URL, local network stability | Query GET /v1/terminal/sessions/{id} to retrieve the latest status before retrying |
| Receipt printed but no webhook or callback arrived | H2H | Whether the receipt indicates a completed transaction and whether this is a BRI flow | For BRI, call POST /v1/terminal/sessions/{id}/retry so the app can verify status and redo the transaction if needed |
| Payment successful, but your server received no webhook | H2H | Webhook endpoint availability and the latest Payment Session state | Query GET /v1/terminal/sessions/{id} and reconcile your backend from the latest session status |
| Timeout on request | C2C | Whether the terminal still shows an in-progress transaction | Cancel the transaction on the terminal if it has not completed. Otherwise, void the transaction and redo it |
| Receipt printed and no response | C2C | Whether the terminal is still on the transaction summary or detail screen | Make sure the transaction summary or detail screen on the terminal is already closed. Otherwise, void the transaction and redo it |
| Cannot connect to Terminal Gateway | C2C | Gateway service status, port 8189, terminal IP address, same-network access | Restore gateway connectivity, correct the device configuration, and retry only after the gateway is reachable |
| Requests fail with authentication or device configuration errors | C2C | CLIENT_KEY, terminal device setup, terminal ID match | Re-initialize the SDK with the correct client key and verify the configured terminal device |
H2H scenarios
Terminal does not respond to a real-terminal payment
Terminal does not respond to a real-terminal payment
What this usually means: The Terminal API accepted the request, but the terminal is not reachable through the SDK or gateway layer.Check these items:
- Confirm the terminal appears connected or ready in your app or Gateway
- Verify the terminal is registered with the correct
terminal_id - Make sure the terminal and your app can reach each other on the network
- Confirm you are using the correct environment for the terminal registration
- Restart the terminal connection if the device appears offline
- Retry the payment only after the terminal returns to a healthy state
Payment finished on the terminal, but your app received no final response
Payment finished on the terminal, but your app received no final response
What this usually means: The terminal may have completed the payment, but your app or callback handler did not receive the final state.Check these items:
- Query the latest Payment Session status
- Review webhook or callback logs
- Verify the callback URL is reachable and returns HTTP
200 - Check for intermittent network issues between the terminal, app, and backend
- Call
GET /v1/terminal/sessions/{id}to confirm the latest authoritative state - Update your order state from the latest session result instead of creating a new payment immediately
Receipt printed, but no webhook or callback arrived
Receipt printed, but no webhook or callback arrived
This recovery flow is especially important for BRI terminals.
- Call
POST /v1/terminal/sessions/{id}/retry - Let the app verify the current transaction status and redo the payment only if the original transaction is incomplete
- The terminal printed a receipt
- Your app or backend never received the final callback
- You need the terminal side to verify whether the payment really completed
Payment successful, but your server received no webhook
Payment successful, but your server received no webhook
What this usually means: The payment may be complete, but webhook delivery to your backend failed or was delayed.Check these items:
- Webhook endpoint availability
- Server logs and firewall configuration
- Whether the webhook handler returns HTTP
200
- Query
GET /v1/terminal/sessions/{id}to retrieve the latest status - Reconcile the order from the Payment Session status before you consider a retry
C2C scenarios
Timeout on request
Timeout on request
What this usually means: Your app did not receive a timely response from the terminal or Gateway, but the terminal may still be processing the transaction.Next action:
- Cancel the transaction on the terminal if it has not completed
- If the payment already completed, void the transaction and redo it
Receipt printed and no response
Receipt printed and no response
What this usually means: The terminal completed a payment or receipt action, but your app did not get the response back from the C2C flow.Check these items:
- Confirm whether the terminal is still showing the transaction summary or detail screen
- Confirm whether the operator already dismissed the transaction result on the terminal
- Make sure the transaction summary or detail screen on the terminal is already closed
- If the transaction already completed and you need to reverse it, void the transaction and redo it
Cannot connect to Terminal Gateway
Cannot connect to Terminal Gateway
What this usually means: The SDK cannot reach the local Gateway service or the configured terminal device.Check these items:
- Verify the Gateway service is running
- Confirm the configured port is
8189 - Verify the terminal IP address is correct
- Make sure your app and Gateway are on the same reachable network
- Fix the local connectivity issue first
- Retry terminal commands only after the Gateway is reachable again
Authentication failed or no terminal device is configured
Authentication failed or no terminal device is configured
What this usually means: The SDK is initialized with the wrong
CLIENT_KEY, the configured terminal does not match, or no default device is set.Next action:- Re-initialize the SDK with the correct
CLIENT_KEY - Verify the configured terminal device uses the correct terminal ID and IP address
- Set or pass the intended terminal device before sending the next command
Recovery actions
Use the recovery action that matches the current state of the transaction:| Action | When to use it | Applies to |
|---|---|---|
| Cancel the transaction | The terminal is still waiting for completion and the transaction has not finished | C2C |
| Void the payment | The payment already completed on the terminal, but you need to reverse it before retrying | H2H, C2C |
| Query the latest Payment Session | The payment outcome is unclear and you need the latest backend-confirmed status | H2H |
| Retry the Payment Session | A receipt printed or the transaction looks stuck after terminal-side processing, and you need the app to verify status and redo only if incomplete | H2H |
| Restart the connection | The terminal or Gateway is offline, unreachable, or stuck in an unhealthy state | H2H, C2C |
For H2H, treat the Payment Session as the source of truth before you initiate another payment. For C2C, confirm the terminal state first so you do not create duplicate customer-facing actions.
Related docs
Errors & Simulations
Review API-side errors, simulation amounts, and real-terminal testing guidance.
Gateway App Configuration
Check device status colors, IP address setup, and Gateway connectivity.
Terminal H2H iOS SDK
Review H2H setup details and platform-specific recovery options.
Terminal C2C iOS SDK
Review C2C SDK setup details and local Gateway communication guidance.