Skip to Content
ResourcesFAQIntegration Issues

Integration Issues

This page summarizes common issues when integrating SUNBAY payment system.

What to do if SDK installation fails?

Java SDK

# Check Maven configuration
mvn dependency:tree | grep sunbay
 
# Clean cache and reinstall
mvn clean install -U

Node.js SDK

# Clean cache
npm cache clean --force
 
# Reinstall
npm install @sunbay/sunbay-nexus-sdk

Python SDK

# Reinstall
pip install sunbay-nexus-sdk

How to resolve SDK version conflicts?

  1. Check dependency versions
  2. Upgrade to latest version
  3. Exclude conflicting dependencies
<!-- Maven exclude dependencies -->
<dependency>
    <groupId>com.sunmi</groupId>
    <artifactId>sunbay-nexus-sdk-java</artifactId>
    <version>1.0.8</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting-group</groupId>
            <artifactId>conflicting-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

How to check SDK version?

Java

<!-- Check in pom.xml -->
<dependency>
    <groupId>com.sunmi</groupId>
    <artifactId>sunbay-nexus-sdk-java</artifactId>
    <version>1.0.8</version>
</dependency>

Node.js

npm list @sunbay/sunbay-nexus-sdk

Python

pip show sunbay-nexus-sdk

Local Integration

What if Tapro app is not installed?

Solution:

  1. Download Tapro from app store
  2. Or download APK from SUNBAY official website
  3. Install and retry connection

What to do if terminal connection fails?

App-to-App Mode:

  • Confirm Tapro is installed and running
  • Check app permissions
  • Restart both apps

Cable Mode:

  • Check cable connection
  • Confirm driver is installed
  • Check serial port configuration

LAN Mode:

  • Confirm devices are on same network
  • Check firewall settings
  • Test connectivity with ping

What to do if device discovery fails?

LAN Mode Device Discovery:

  1. Check Network Connection
# Ping terminal IP
ping 192.168.1.100
 
# Check port
telnet 192.168.1.100 8080
  1. Check Firewall
  • Allow UDP broadcast (port 8888)
  • Allow TCP connection (port 8080)
  1. Manual IP Configuration
    • If automatic discovery fails, you can manually specify terminal IP address in SDK configuration
    • Refer to the corresponding platform’s SDK documentation for specific configuration methods

What if serial port cannot be opened?

Windows:

  1. Check COM port in Device Manager
  2. Confirm driver is installed correctly
  3. Check if port is occupied by other programs

Linux:

# View serial port devices
ls -l /dev/ttyUSB*
 
# Add user to dialout group
sudo usermod -a -G dialout $USER
 
# Re-login for permissions to take effect

Cloud Integration

What to do if connection times out?

Check Network Connection:

# Test API connectivity
curl -I https://open.sunbay.us
 
# Check DNS resolution
nslookup open.sunbay.us

Adjust Timeout Settings:

// Java SDK
NexusClient client = new NexusClient.Builder()
    .apiKey(apiKey)
    .baseUrl("https://open.sunbay.us")
    .connectTimeout(30000)  // 30 seconds
    .readTimeout(60000)     // 60 seconds
    .build();

What to do if SSL certificate verification fails?

Causes:

  • System time incorrect
  • Missing root certificates
  • Using self-signed certificate

Solutions:

  1. Sync System Time
# Linux/Mac
sudo ntpdate -u time.nist.gov
 
# Windows
w32tm /resync
  1. Update Root Certificates
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install ca-certificates
 
# CentOS/RHEL
sudo yum update ca-certificates
  1. Import Certificate to Java
# Download certificate
openssl s_client -connect open.sunbay.us:443 -showcerts
 
# Import to Java keystore
keytool -import -alias sunbay -file sunbay.crt \
  -keystore $JAVA_HOME/jre/lib/security/cacerts

What to do about request rate limiting?

Error Code: S04 - Interface call frequency exceeded

Solutions:

  1. Reduce Request Frequency

    • Reduce concurrent requests
    • Increase request intervals
    • Use queue to control request frequency

  2. Handle Rate Limit Errors

catch (SUNBAYBusinessException e) {
    if ("S04".equals(e.getCode())) {
        // Rate limit exceeded, wait then retry
        Thread.sleep(1000); // Wait 1 second
        // Retry request
    }
}
  1. Contact Technical Support to Increase Limit

Data Format

What to do if JSON parsing error occurs?

Common Causes:

  • Incorrect JSON format
  • Character encoding issues
  • Special characters not escaped

Debugging Methods:

// Print raw response
console.log('Raw response:', responseText);
 
// Validate JSON format
try {
    const data = JSON.parse(responseText);
} catch (e) {
    console.error('JSON parse error:', e.message);
    console.error('Invalid JSON:', responseText);
}

Use Online Tools for Validation:

What to do if amount format is wrong?

Correct Amount Format:

// ✅ Correct - Use smallest currency unit (cents)
SaleAmount amount = SaleAmount.builder()
    .orderAmount(10000)  // 100.00 USD = 10000 cents
    .priceCurrency("USD")
    .build();
 
// ❌ Wrong - Using decimal
.orderAmount(100)  // Wrong: This represents 1.00 USD, not 100.00 USD

Amount Conversion:

// Dollars to cents
int amountInCents = (int) Math.round(amountInDollars * 100);
 
// Cents to dollars
double amountInDollars = amountInCents / 100.0;

What to do if date/time format is wrong?

Use ISO 8601 Format:

// ✅ Correct
"2025-01-08T10:30:00Z"
"2025-01-08T10:30:00+08:00"
 
// ❌ Wrong
"2025/01/08 10:30:00"
"01-08-2025 10:30:00"

JavaScript Example:

// Generate ISO 8601 format
const timestamp = new Date().toISOString();
 
// Parse ISO 8601 format
const date = new Date('2025-01-08T10:30:00Z');

Environment Configuration

How to switch between test/production environments?

SDK Configuration:

// Test and production environments use the same baseUrl
NexusClient client = new NexusClient.Builder()
    .apiKey(apiKey)  // Use test or production environment API Key
    .baseUrl("https://open.sunbay.us")  // Default value, can be omitted
    .build();

Use Environment Variables:

# .env file
SUNBAY_API_KEY=your_api_key

How to configure log level?

Java:

// logback.xml
<logger name="com.sunmi.sunbay.nexus" level="DEBUG"/>

Node.js:

const { NexusClient } = require('@sunbay/sunbay-nexus-sdk');
 
const client = new NexusClient({
    apiKey: apiKey,
    baseUrl: 'https://open.sunbay.us',
    // SDK uses standard logging library, log level can be controlled via environment variables
});

Python:

import logging
logging.basicConfig(level=logging.DEBUG)

Debugging Tips

How to view requests and responses?

Enable Debug Logging:

SDK uses standard logging libraries; you can configure log level through logging framework:

Java:

<!-- logback.xml -->
<logger name="com.sunmi.sunbay.nexus" level="DEBUG"/>

Node.js:

// Use environment variable
process.env.DEBUG = 'sunbay:*';

Python:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger('sunbay_nexus_sdk').setLevel(logging.DEBUG)

Use Packet Capture Tools:

  • Charles Proxy
  • Fiddler
  • Wireshark

How to test Webhook?

Use Local Tunnel Tools:

# ngrok
ngrok http 3000
 
# Get public URL
https://abc123.ngrok.io

Use Webhook Testing Tools:

How to simulate different payment scenarios?

Sandbox environment simulates different payment scenarios through test amounts, no need to use specific test card numbers:

// Successful payment: Use any non-special amount (e.g., 100)
amount: 100
 
// Card declined: Use test amount 8888
amount: 8888
 
// Insufficient balance: Use test amount 8887
amount: 8887
 
// Transaction timeout: Use test amount 7777
amount: 7777

See Test Scenarios for details

Performance Optimization

How to improve request speed?

  1. Use Connection Pool
// Configure connection pool
HttpClient httpClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .build();
  1. Enable HTTP/2
HttpClient client = HttpClient.newBuilder()
    .version(HttpClient.Version.HTTP_2)
    .build();
  1. Use CDN
  • Use nearby API endpoints
  • Enable gzip compression
  1. Batch Operations
  • Merge multiple query requests
  • Use batch query interface

How to reduce memory usage?

  1. Release Resources Promptly
// NexusClient implements AutoCloseable
try (NexusClient client = new NexusClient.Builder()
        .apiKey(apiKey)
        .build()) {
    // Use client
} // Auto-close
  1. Reuse Client Instances
// Create once, reuse globally (recommended)
NexusClient client = new NexusClient.Builder()
    .apiKey(apiKey)
    .build();
// Reuse same instance throughout application lifecycle
Last updated on
Account & AuthenticationPayment Issues