--- title: 'How to Troubleshoot Payment Problems' url: 'https://manuals.remository.com/payage/troubleshooting/how-to-troubleshoot-payment-problems' markdown: 'https://manuals.remository.com/payage/troubleshooting/how-to-troubleshoot-payment-problems.md' date: '2026-11-14' description: 'The first thing to do with any kind of payment problem in a new installation is to go back and double check the settings in both the gateway account and the Payage account. The vast majority of payment problems are caused by failure to follow the documentation. Payment problems break down into thre…' taxonomy: category: - docs --- [](#) [ edit this page](https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/pages/27.troubleshooting/01.how-to-troubleshoot-payment-problems/docs.md) # How to Troubleshoot Payment Problems The first thing to do with any kind of payment problem in a new installation is to go back and double check the settings in both the gateway account and the Payage account. The vast majority of payment problems are caused by failure to follow the documentation. Payment problems break down into three main categories. (a) Clicking the payment button results in an immediate error. (b) The browser does not return to your site after payment. (c) The browser does return to your site after payment, but an error occurs. We'll deal with each case separately. ## Case (a) Clicking The Payment Button Results In An Error This case is unusual. If you can't resolve it please contact us, giving the information listed below. ## Case (b) The Browser Does Not Return To Your Site After Payment With PayPal, this may be because you did not enable the "Auto Return" option in your PayPal account. In most cases a payment gateway cannot return to your site if it is running on a localhost. If you develop your site on a local machine, you can do payment testing using the Offline gateway, but in most cases you cannot test real payments in a local environment. Payment gateways also cannot return to a page that requires the user to log in. The payment return request is from the payment gateway server, not from the user's device. Since the payment gateway does not have the Joomla session cookie, any request to a logged-in page will fail. ## Case (c) The Browser Returns To Your Site, But An Error Occurred Once the customer returns to your site after payment, Payage must perform security checks to ensure that the correct payment was actually made. Any misconfiguration in Payage or your gateway account will cause these checks to fail. When a payment error occurs, do not expect to see the real reason for the problem on the front end of your site. E-commerce applications must try to avoid showing technical error messages to customers. Instead, the customer should see a non-technical message. For example, with the Payage plugin, the user might see a message like this: > There was a problem with your payment. Please try again or contact us for assistance. Your transaction number is feb450db0061f031817baea15e520ae4. The technical details of the error are stored in Payage. You need to find the payment in the payment list and click on it to find the cause of the error. In this example we forced an error to occur by specifying the wrong Token in a PayPal gateway account. On the payment details page, we see this: ![](https://manuals.remository.com/payage/user/pages/27.troubleshooting/01.how-to-troubleshoot-payment-problems/p-61_1.png) The payment history shows that the PDT (Payment Data Transfer) verification process failed with error code 4020. This was followed a few minutes later by an IPN (Instant Payment Notification) update that changed the payment status to success. However, the damage was done; the customer would have seen this as a failed transaction. ## If You Find An Error Code In A Payment, Google It! We can't list all the error codes for all the gateways in this guide. There are too many, and some require long explanations. PayPal errors are notoriously difficult to interpret, but in the example above a quick Google of "PayPal error 4020" would quickly reveal that this error is related to the account token specified on the call to the Payment Data Transfer interface. ## How To Ask For Help With A Payment Error If you contact us about a payment error, please include the following information: (a) What kind of payment problem is it (a, b, or c)? (b) Is there a Payage payment record? If so, please tell us the exact text of any error message you can see there, and if possible please attach a download of the Payage payment. (c) If there is no Payage payment record, please try to get a Payage trace file of the problem (see the Trace Mode section). (d) Please include a screenshot of any errors shown on the front end. (e) Please include a screenshot of the gateway configuration page (remove passwords if you wish). (f) Please tell us the versions of Joomla, Payage and the relevant gateway addon. Unless you include all of this information, we will assume you have not yet found this section of the user guide and we will ask you to work through this section before contacting us again. [ ](https://manuals.remository.com/payage/troubleshooting) [](https://manuals.remository.com/payage/troubleshooting/paypal-ssl-certificate-problem) --- ## Navigation - Parent: [Troubleshooting](https://manuals.remository.com/payage/troubleshooting.md) - Next: [PayPal "SSL certificate problem"](https://manuals.remository.com/payage/troubleshooting/paypal-ssl-certificate-problem.md)