Enable Verbose Logging
Log all incoming webhook payloads and your handler's responses
Troubleshooting
Troubleshooting
Having issues with your integration? Find solutions to common problems below, or contact support for personalized help.
Common Issues
Webhook not received
Possible Causes
- Webhook URL not configured in dashboard
- Firewall blocking incoming requests
- SSL certificate issues
- Endpoint returning non-2xx status
Solutions
- Verify URL is configured in SanPay settings
- Check server firewall allows external POST requests
- Ensure valid SSL certificate (no self-signed in production)
- Return 200 OK immediately, process async
Signature verification failed
Possible Causes
- Wrong webhook secret
- Request body modified by middleware
- Clock skew between servers
Solutions
- Copy webhook secret exactly from dashboard
- Verify raw body before any JSON parsing
- Allow ±5 minute timestamp tolerance
SDK modal not opening
Possible Causes
- Origin not whitelisted
- Invalid session ID
- JavaScript error on page
Solutions
- Add your domain (with protocol) to allowed origins
- Verify session was created successfully
- Check browser console for errors
Payment stuck on PENDING_SELECTION
Possible Causes
- Customer hasn't selected a currency yet
- Session expired
Solutions
- This is normal—customer chooses crypto in the modal
- Check expiresAt timestamp
Order not updating after payment
Possible Causes
- Webhook handler error
- Database transaction failed
- Event processed but duplicate ignored
Solutions
- Check webhook handler logs for errors
- Verify order ID matching logic
- Check eventId deduplication implementation
Debugging Tips
Check Dashboard
View webhook delivery logs in the SanPay admin panel
Use Test Mode
Debug with testnet payments before going live
Verify API Keys
Ensure you're using matching key pairs (test with test, live with live)
Error Code Reference
| Code | HTTP Status | Cause | Solution |
|---|---|---|---|
UNAUTHORIZED | 401 | Invalid or missing API key | Check API key is correct and active |
FORBIDDEN | 403 | Origin not allowed | Add your domain to allowed origins |
SESSION_EXPIRED | 400 | Checkout session timed out | Create a new checkout session |
INVALID_AMOUNT | 400 | Amount format invalid | Use numeric string: "99.99" |
UNSUPPORTED_CURRENCY | 400 | Currency not enabled | Check supported currencies in dashboard |
RATE_LIMITED | 429 | Too many requests | Implement exponential backoff |
Need More Help?
If you can't find a solution here:
Documentation
Browse our complete API reference
Email Support
[email protected] for technical issues
Dashboard Logs
View detailed request and webhook logs