Integration Issues (3rd Party) – Complete Troubleshooting Guide

Overview

Integrations in Hana POS connect the system with external third-party platforms, such as:

• Payment gateways (for transaction processing)
• Website / eCommerce platforms (for online orders)
• Marketing tools (email/SMS campaigns)
• Wire services and delivery systems

? These integrations enable automated data flow between systems.

Why This Matters (Support Context)

Integration issues are high-impact because they involve external dependencies outside Hana POS control.

Failures can disrupt:

• Order synchronization
• Payment processing
• Customer communication
• Data consistency

? Key Insight:
Most integration issues are caused by:

• Expired or incorrect credentials
• Misconfiguration in settings
• API connectivity failures
• Network interruptions

? These are usually configuration or authentication issues, not system bugs.

Common Symptoms Reported by Florists

Florists may report:

• “Integration is not working”
• “Data is not syncing”
• “Connection failed”
• “Orders not coming from website”
• “Payments not processing”
• “Error while connecting integration”

Root Cause Categories

1. Expired or Invalid Credentials (Most Common Cause)

• API keys expired
• Passwords changed
• Tokens invalid

2. Incorrect Configuration

• Integration not set up correctly
• Missing required fields
• Incorrect environment (live vs test)

3. API Connectivity Issues

• Third-party service downtime
• API endpoint failures

4. Network Problems

• Unstable internet connection
• Firewall or security restrictions

5. Permission / Access Issues

• Insufficient access rights
• Integration not authorized properly

Step-by-Step Troubleshooting Process

⚠️ Always identify the integration first before troubleshooting.

Step 1: Identify Integration (Critical First Step)

Ask:

“Which integration are you referring to?”

Examples:

• Payment gateway
• Website platform
• Marketing tool

? Why this matters:

• Each integration has a different configuration and dependency

Step 2: Verify Credentials

Check:

• API keys
• Username/password (if applicable)
• Access tokens

? Key Insight:
Credential issues are the #1 cause of integration failures.

Step 3: Reconnect Integration

• Disconnect the integration
• Reconnect using correct credentials

? Why this works:
Refreshes authentication and resolves token/session issues.

Step 4: Verify Configuration Settings

• Ensure all required fields are filled
• Confirm correct setup:
  • Environment (Live/Test)
  • Mapping (if applicable)

? Why this matters:
Incorrect configuration prevents proper communication.

Step 5: Test Connection

• Perform a test action:
  • Process a test payment
  • Sync a test order
  • Send a test campaign

? Goal:
Confirm integration is functioning correctly.

Step 6: Check Network / Connectivity

• Ensure stable internet connection
• Disable VPN/firewall temporarily (if applicable)

? Why this matters:
Network restrictions can block API communication.

Critical Scenarios & Handling

Integration Not Connecting

Possible causes:

• Invalid credentials
• Configuration error

✅ Action:

• Re-enter credentials
• Reconnect integration

Data Not Syncing

Possible causes:

• API delay
• Incorrect configuration

✅ Action:

• Test sync
• Verify setup

Connection Failed Error

Possible causes:

• API unavailable
• Network issue

✅ Action:

• Retry connection
• Check network

Payments / Orders Not Flowing

Possible causes:

• Integration misconfigured
• Credentials expired

✅ Action:

• Verify setup
• Test transaction

Best Practices for Support Agents

• ✅ Always identify which integration is affected
• ✅ Verify credentials first
• ✅ Reconnect integration before deeper troubleshooting
• ✅ Perform a test action to confirm fix
• ❌ Do NOT assume system issue without credential validation
• ❌ Avoid escalation without testing connection

Escalation Guidelines

Escalate ONLY IF:

• API failures persist after reconnection
• Integration fails despite valid credentials and configuration
• Multiple users report the same issue
• Third-party service appears unresponsive

? Include in escalation:

• Integration name (payment gateway, website, etc.)
• Error message (if any)
• Steps already attempted
• Test results
• Screenshots/logs (if available)

FAQ Section

Q1: Why is my integration not working?

Most commonly due to:

• Expired or incorrect credentials

Q2: Why is data not syncing?

Possible reasons:

• Configuration issue
• API delay

Q3: Do I need to reconnect integration regularly?

Only if credentials expire or connection fails.

Q4: Can network issues affect integrations?

Yes, unstable connections or firewalls can block integration.

Support Agent Script (Standardized)

Opening

“I understand the integration is not working. Let’s check a few things step by step.”

Clarification

“Which integration are you referring to?”

Guided Troubleshooting

“Let’s verify your credentials and reconnect the integration.”

Reassurance

“This is usually caused by credential or configuration issues and is quick to fix.”

Closure (Resolved)

“The integration is now working correctly.”

Closure (Escalation)

“Thanks for trying those steps. I’ll escalate this for further review.”