Troubleshooting
Troubleshooting
Use this guide when your ePay integration does not behave as expected.
Start with the symptom that matches your issue. Most problems are caused by environment mismatch, incorrect credentials, unreachable notification URLs or order status handling.
Before you troubleshoot
Check these first:
- Are you using the correct environment?
- Are you using the correct API key?
- Are you using the correct Point of Sale ID?
- Is your request made from the backend?
- Is your notification URL publicly available?
- Are you checking backend logs?
- Are you relying on server-side payment results instead of redirects alone?
API request fails
400 Bad Request
The request is invalid.
Check that:
- Required fields are included
- Field names are correct
- Amount is in the correct format
- Currency is supported
- URLs are valid
- The request body is valid JSON
401 Unauthorized
The API key is missing or invalid.
Check that:
- The
Authorizationheader is included - The API key is correct
- The API key belongs to the environment you are using
- The request is made from your backend
- There are no extra spaces in the API key
Example:
Authorization: Bearer <TEST_API_KEY>422 Validation Error
The request is understood, but one or more values are not valid.
Check that:
- The Point of Sale ID exists
- The Point of Sale ID belongs to the correct environment
- The amount is allowed
- The currency is available
- The payment method is available
- URLs are accepted by your configuration
429 Rate Limited
Too many requests were sent in a short period.
Check that:
- Your system is not retrying too aggressively
- You use idempotency when creating payments
- You use retry handling with backoff
- You are not creating duplicate payments from the frontend
Payment window does not open
Check that:
- The payment was created successfully
- You received a valid payment window URL
- You redirect the customer to the correct URL
- The payment session has not expired
- The Point of Sale ID is correct
- The amount and currency are valid
If the payment session is created from your backend, inspect the response and backend logs.
Payment fields do not appear in Blocks
Check that:
- ePay.js is loaded
- The session ID is valid
- The session key is valid
- The session belongs to the correct environment
- The container selectors match your HTML
- The payment session has not expired
- There are no JavaScript errors on the page
Example:
epay.mountFields({ cardNumber: "#card-number", expiryDate: "#expiry-date", cvc: "#cvc",});Make sure the elements exist in the page before mounting.
Payment method does not appear
Check that:
- The payment method is enabled
- The payment method is available in the current environment
- The Point of Sale supports the payment method
- Your account has access to the payment method
- Any required merchant registration has been completed
- Your plugin or integration is using the correct environment
For wallet payment methods, additional setup may be required.
Customer reaches success page, but order is not paid
The success page should not be the only source of truth.
Check that:
- Your notification URL or webhook is configured
- Your backend receives the payment result
- Your backend verifies the payment result
- Your backend matches the payment to the correct order
- Your backend updates the order status
Use server-side payment results to mark orders as paid.
Order is marked as paid twice
Your payment result handler may not be idempotent.
Check that:
- You store the payment ID or transaction ID
- You check whether the payment has already been processed
- Duplicate notifications return success without repeating side effects
- You do not send duplicate confirmation emails
- You do not fulfill the same order twice
Recommended pattern:
if (await hasProcessedPayment(payment.id)) { return { ok: true };}await processPayment(payment);await markPaymentAsProcessed(payment.id);Notification URL is not called
Check that:
- The notification URL is included when creating the payment
- The URL is publicly available
- The URL uses HTTPS
- Your firewall or proxy allows requests from ePay
- Your endpoint accepts the request method used by ePay
- Your endpoint returns a successful response
- Your backend logs incoming requests
A localhost URL cannot be reached by ePay.
This will not work:
http://localhost:3000/api/epay/notificationUse a public HTTPS URL while testing notifications.
Notification URL is called, but fails
Check that:
- Your endpoint can parse the request body
- Your endpoint handles the payment status correctly
- Your endpoint can find the order
- Your endpoint handles duplicate notifications safely
- Your endpoint returns a successful response when processing succeeds
- Your endpoint logs errors
Do not return an error response after processing a notification successfully.
Plugin payment does not work
Check that:
- The plugin is installed and enabled
- The plugin uses the test environment while testing
- The API key is correct
- The Point of Sale ID is correct
- Payment methods are enabled
- The webshop can receive payment notifications
- Order status settings are configured correctly
If the plugin has a log section, check the plugin logs first.
Test works, but live does not
Check that:
- You switched from test API key to live API key
- You switched from test Point of Sale ID to live Point of Sale ID
- Live payment methods are enabled
- Your acquirer agreement is active
- Your production notification URL is configured
- Your success and failure URLs point to production
- You are not using test credentials in production
Live works, but test does not
Check that:
- You are using test credentials in the test environment
- The payment method is available in test
- The Point of Sale ID belongs to test
- Your test notification URL is reachable
- Your local tunnel is running, if used
Customer cannot complete 3D Secure
Check that:
- The payment method supports the test scenario
- The browser allows redirects or popups required by the flow
- The customer is not blocked by browser extensions
- Your success and failure URLs work
- Your integration handles redirects correctly
Amount or currency is wrong
Check that:
- Amount is sent in the expected unit
- Currency is correct
- The order amount matches the payment amount
- The currency is supported by the Point of Sale
- You verify amount and currency before marking the order as paid
Useful logs to collect
When troubleshooting, collect:
- Request timestamp
- Environment
- Point of Sale ID
- Order reference
- Payment ID
- Request body
- Response body
- HTTP status code
- Notification payload
- Backend error logs
Do not log sensitive payment data.
When to contact support
Contact support if you have checked the relevant sections and still cannot resolve the issue.
Include:
- Environment
- Point of Sale ID
- Payment ID, if available
- Order reference
- Timestamp
- Error message
- What you expected to happen
- What actually happened
Do not send API keys or sensitive payment data.