Errors & Simulations
Error handling is an essential part of integrating with the Xendit’s Payment Terminal API. This section covers error codes, error handling best practices, and testing simulations.Error Data Structure
An error occurs when the HTTP status is not 200.string
Error code
string
Error message
Error Codes
Validation Errors
INVALID_REQUEST
Missing or invalid parameters
Occurs when required fields are missing or contain invalid data types or formats.
1
Check Parameters
Verify all required parameters are present and correctly formatted
2
Validate Data Types
Ensure data types match the API specification
3
Retry with Corrected Data
Fix the request and retry
DUPLICATED_REQUEST
Duplicated reference id
Occurs when the same idempotency key is used for multiple requests.
1
Check Idempotency Key
Ensure the idempotency key is unique across all environments
2
Generate New Key
Create a new unique idempotency key
3
Retry Request
Retry with the new idempotency key
Authentication Errors
UNAUTHORIZED
Unauthorized, invalid API Key
Occurs when the API key is missing, invalid, or lacks necessary permissions.
1
Verify API Key
Check that the API key is correct and active
2
Check Encoding
Ensure the API key is properly base64 encoded with the colon
3
Contact Support
If the issue persists, contact Xendit support
Terminal & Configuration Errors
TERMINAL_NOT_FOUND
The terminal id is not configured for your account
Occurs when the specified terminal ID is not registered or configured for your account.
1
Verify Terminal ID
Double-check the terminal ID matches exactly
2
Check Registration Status
Contact support to verify registration is complete
3
Confirm Environment
Ensure using test API key with test terminal registration
COMMAND_NOT_SUPPORTED
The command currently not supported for this terminal
Occurs when attempting to use a feature or command not available on the specified terminal.
1
Check Terminal Capabilities
Verify the terminal supports the requested command
2
Use Alternative Terminal
Try a different terminal that supports the feature
3
Contact Support
Ask about terminal upgrade options if needed
Business Logic Errors
CURRENCY_NOT_SUPPORTED
Currency is not supported for your account
Occurs when attempting to process a payment in a currency not enabled for your account.
1
Check Supported Currencies
Verify which currencies are enabled for your account
2
Contact Support
Request currency activation from Xendit support
3
Use Supported Currency
Retry with a supported currency
Error Handling Best Practices
Parse Error Response
Always parse the error response and use the error code or message to determine the cause of the failure
Log Errors
Log error responses for debugging and monitoring purposes
Retry Logic
Implement appropriate retry logic for transient errors
User Feedback
Provide meaningful error messages to end users when appropriate
Example Error Response
Simulations
Perfect for merchants without physical terminals yet! You can start integrating immediately using our simulation capabilities. No need to wait for terminal delivery - test payment flows, error handling, and webhook integrations using special test amounts and terminal IDs.Getting Started Without Hardware: Use any
terminal_id value (like SIM001) and special test amounts to simulate different payment scenarios. This is ideal for merchants waiting on terminal delivery or those who want to build and test their integration before hardware arrives.Payment Session Simulations
Testing with Real Terminals in Test Mode
For detailed instructions on registering and testing with real terminals in test mode, see the Physical Terminal Testing section in our quickstart guide.Key Differences: Real Terminal Testing vs Simulation
- Real Terminal Testing
- Simulation Testing
Uses physical hardware with test transactions
- ✓ Real card reader interactions
- ✓ Real money movement
- ✓ Actual terminal display prompts
- ✓ Physical button presses and card taps
- ✓ Network connectivity testing
- ✓ Complete hardware validation
- ! Requires terminal registration
- ! Dependent on physical hardware
Troubleshooting Real Terminal Testing
Terminal Not Responding
Terminal Not Responding
Symptoms: API calls succeed but terminal doesn’t show payment prompts
1
Check Terminal Status
Verify terminal shows “Connected” in Terminal Gateway
2
Verify Registration
Confirm terminal ID is registered for test mode
3
Test Network Connection
Ensure terminal has stable network connectivity
4
Restart Terminal Gateway
Restart the Terminal Gateway app/SDK connection
TERMINAL_NOT_FOUND Error
TERMINAL_NOT_FOUND Error
Symptoms: API returns error code
TERMINAL_NOT_FOUND1
Verify Terminal ID
Double-check the terminal ID matches exactly
2
Check Registration Status
Contact support to verify registration is complete
3
Confirm Environment
Ensure using test API key with test terminal registration
Transactions Fall Back to Simulation
Transactions Fall Back to Simulation
Symptoms: API works but no physical terminal interaction
1
Confirm Registration
Verify terminal is registered (unregistered terminals auto-simulate)
2
Check Terminal Gateway Mode
Ensure Terminal Gateway is in test mode, not simulation mode
3
Validate Terminal Connection
Confirm terminal shows active connection status
Best Practice: Start with simulation testing for initial integration, then move to real terminal testing for final validation before production.