Troubleshooting

Payment Not Received

Symptoms

• Customer says they paid, but the transaction shows "Pending" or no transaction appears.

Diagnosis Steps

1. Check the blockchain: Use a blockchain explorer (e.g., Etherscan, Blockchain.com) to verify the transaction hash. Confirm the payment was sent to the correct address.

1. Check confirmations: The payment may be waiting for the required number of confirmations. Go to your dashboard → Transactions and look for the transaction status.

1. Check the amount: If the customer sent less than the required amount, the transaction will be marked as underpaid unless "Accept Underpayments" is enabled.

1. Verify the address: Ensure the customer sent to the correct wallet address and on the correct network. A common mistake is sending ERC-20 tokens to a TRC-20 address (different networks, funds may be lost).

1. Check the cryptocurrency: Verify the customer paid with the cryptocurrency they selected, not a different token on the same network.

Resolution

• If the transaction is confirmed on the blockchain but not reflected in QuantaPay, use the check-transaction API to force a re-check.
• If the payment was sent to the wrong address or wrong network, QuantaPay cannot recover the funds.

Webhook Not Triggering

Symptoms

• Payments complete in the QuantaPay dashboard but your server doesn't receive webhook notifications.

Diagnosis Steps

1. Verify webhook URL: Go to Settings → Payments → Webhook and confirm the URL is correct.

1. Check endpoint accessibility: Ensure your webhook endpoint is publicly accessible via HTTPS. Test with curl:

   curl -X POST https://yoursite.com/wp-json/quantapay/webhook \
     -H "Content-Type: application/json" \
     -d '{"test": true}'

1. Check server logs: Look for incoming POST requests to your webhook endpoint. If there are none, the issue is with delivery. If there are 500 errors, the issue is in your handler code.

1. Firewall / WAF: If using Cloudflare, ensure the webhook endpoint is allowed (see WordPress / WooCommerce for Cloudflare configuration).

1. Check webhook status: In your dashboard → Transactions, the "Webhook" column shows 1 if the webhook was sent for that transaction.

Resolution

• Fix the webhook URL or endpoint accessibility.
• Temporarily use a webhook testing service (webhook.site) to confirm QuantaPay is sending webhooks.
• As a fallback, poll the get-checkout-session API to check payment status.

API Connection Errors

Symptoms

• API calls return errors, timeouts, or unexpected responses.

Common Issues

Debugging Tips

1. Test with curl: Use curl to isolate whether the issue is in your code or the API:

   curl -X POST https://cloud.quantapay.app/api.php \
     -d "function=get-balances" \
     -d "api-key=YOUR_API_KEY"

1. Check response format: All responses follow {"success": true/false, ...}. Parse the success field before accessing response.

1. Log requests: Log the full request and response for debugging.

WordPress Plugin Issues

Order status not updating

• Verify the webhook URL is configured in both WordPress and QuantaPay Cloud.
• Check the WordPress debug log (wp-content/debug.log) for errors.
• Ensure the WooCommerce order exists and is in "Pending" status.

Plugin settings not saving

• Clear any caching plugins (WP Super Cache, W3 Total Cache, etc.).
• Check file permissions on wp-content/.
• Verify the database user has write permissions.

Checkout redirect not working

• Ensure your site's SSL certificate is valid.
• Check for JavaScript errors in the browser console.
• Verify the QuantaPay Cloud API is accessible from your server.