Common Issue List

This page contains common issues that developers might encounter when integrating with the Swiftrans API and their solutions.

Authentication Issues

Issue: "Invalid token" error

Problem: Getting authentication errors even with correct credentials.

Solution:

1. Ensure you're using the correct login endpoint: /api/v1/login
2. Verify username and password are correct
3. Check that the token hasn't expired (tokens expire after 1 hour)
4. Include the token in the Authorization header: Bearer {token}

// Correct authentication
$loginResponse = login($username, $password);
$token = $loginResponse['data']['access_token'];

// Use token in subsequent requests
$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
];

Issue: "Token expired" error

Problem: Access token expires during API calls.

Solution:

• Implement token refresh logic
• Cache tokens and refresh before expiry
• Handle 401 responses by obtaining new tokens

Request Format Issues

Issue: "Invalid JSON format" error

Problem: API returns validation errors for JSON requests.

Solution:

1. Ensure Content-Type header is application/json
2. Validate JSON syntax before sending
3. Use proper encoding (UTF-8)

// Correct request format
const response = await fetch('https://openapi.swiftrans.id:7654/api/v1/disbursement', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(data)
});

Issue: Missing required fields

Problem: Validation errors for missing fields.

Solution:

• Check API documentation for required fields
• Validate request data before sending
• Use proper data types

Network Issues

Issue: Connection timeout

Problem: Requests timing out or failing to connect.

Solution:

1. Check network connectivity
2. Verify API endpoint URLs (sandbox.swiftrans.id or api.swiftrans.id:7654)
3. Increase timeout values
4. Implement retry logic with exponential backoff

// PHP with retry logic
$maxRetries = 3;
$retryDelay = 1; // seconds

for ($i = 0; $i < $maxRetries; $i++) {
    try {
        $response = makeApiCall();
        break;
    } catch (Exception $e) {
        if ($i === $maxRetries - 1) {
            throw $e;
        }
        sleep($retryDelay * pow(2, $i));
    }
}

Issue: SSL/TLS certificate errors

Problem: SSL verification failures.

Solution:

• Ensure your system has updated CA certificates
• Use HTTPS endpoints only
• Don't disable SSL verification in production

Disbursement Issues

Issue: "Insufficient balance" error

Problem: Disbursement fails due to insufficient funds.

Solution:

• Check balance using /api/v1/balance endpoint before disbursement
• Ensure you have enough funds including fees
• Top up your account if needed

// Check balance before disbursement
const balanceResponse = await fetch('https://openapi.swiftrans.id:7654/api/v1/balance', {
    headers: { 'Authorization': `Bearer ${token}` }
});
const balance = await balanceResponse.json();

if (balance.data.balance >= disbursementAmount) {
    // Proceed with disbursement
} else {
    // Insufficient balance
}

Issue: "Invalid bank account" error

Problem: Bank account validation failures.

Solution:

• Use /api/v1/check-account endpoint to validate before disbursement
• Ensure bank code is supported
• Verify account number format

{
    "bank_code": "5",
    "account_number": "1234567890"
}

Issue: "Duplicate reference ID" error

Problem: Reference ID already exists.

Solution:

• Ensure reference_id is unique for each transaction
• Use timestamp or UUID in reference ID generation
• Check existing transactions before creating new ones

Rate Limiting Issues

Issue: "Too many requests" error (429)

Problem: Hitting API rate limits.

Solution:

1. Implement request throttling
2. Use exponential backoff for retries
3. Cache responses when possible
4. Contact support for higher limits if needed

// Rate limiting with delay
const delay = ms => new Promise(resolve => setTimeout(resolve, ms));

async function makeApiCallWithRateLimit() {
    try {
        return await makeApiCall();
    } catch (error) {
        if (error.status === 429) {
            await delay(5000); // Wait 5 seconds
            return await makeApiCall();
        }
        throw error;
    }
}

Response Handling Issues

Issue: Unexpected response format

Problem: Response doesn't match expected format.

Solution:

1. Check API version in request headers
2. Verify endpoint URL
3. Handle different response formats gracefully

// Robust response handling
try {
    const response = await fetch(url, options);
    const data = await response.json();

    if (!response.ok) {
        throw new Error(data.message || 'API request failed');
    }

    return data;
} catch (error) {
    console.error('API Error:', error);
    throw error;
}

Environment Issues

Issue: Different behavior between sandbox and production

Problem: Code works in sandbox but fails in production.

Solution:

1. Verify you're using production credentials
2. Check production base URL: https://openapi.swiftrans.id:7654
3. Ensure production environment is properly configured
4. Test thoroughly in sandbox before production deployment

Bank-Specific Issues

Issue: Transaction stuck in PROCESS status

Problem: Disbursement remains process for extended periods.

Solution:

1. Check bank processing times (can be up to 30 minutes)
2. Use status polling with reasonable intervals
3. Implement callback URLs for real-time updates
4. Contact support if process exceeds expected timeframe

Issue: Bank maintenance windows

Problem: Transactions fail during bank maintenance.

Solution:

• Check bank maintenance schedules
• Implement retry logic for temporary failures
• Use multiple bank options when possible
• Schedule disbursements outside maintenance windows

Getting Help

If you continue to experience issues:

1. Check Status Page: Visit our status page for known issues
2. Review Logs: Check your application logs for detailed error messages
3. Contact Support: Reach out to our technical support team
4. Community Forum: Join our developer community for peer support

Support Information

• Email: helpdesk@swiftrans.id
• Documentation: https://docs.swiftrans.id