Payment Gateway Troubleshooting

“Help! I manage a PaperCut NG/MF server and users are reporting that when they try to add credit through a payment provider like PayPal, this amount is never added to their PaperCut balance. How do I troubleshoot this?”

You should know that specific steps for troubleshooting Payment Gateways are included in the setup guide for each so you should check for a troubleshooting section in the relevant Payment Gateway Guide.

However, there’s also some general advice that goes for troubleshooting any type of Payment Gateway and that’s what we will discuss below.

Upgrade the Payment Gateway Module

This applies if you have upgraded PaperCut around the time this stopped working. Check to see if there’s a newer version of the Payment Gateway module you should install. Check our page How to set up the Payment Gateway Module to see if you are running the right version of the Payment Gateway Module that applies to your PaperCut NG or MF server.

Make sure the post-back or IPN URL is accessible

The most common problem that we hear is that users have manually added credit, but this amount has not been updated in PaperCut. This usually happens because the Payment Gateway is not able to contact the PaperCut server via the “postback URL” or “IPN URL”. So it’s important to check DNS, firewalls, and proxies to make sure nothing is obstructing this traffic.

Steps:

1. On the PaperCut server navigate to the properties file for the Payment Gateway. On a 64-bit Windows PaperCut MF server this would be located in C:\Program Files\PaperCut MF\server\lib-ext\ and the file will be named something like ext-payment-gateway-<your payment provider>.properties. Open this file with a plain text editor like Notepad.

2. Find the line containing the PostBack or IPN URL. Here are some examples:

   • PayPal WPS: paypal.ipn-url=
   • Official Payments: officialpayments.postback-url=

3. Test to make sure that this URL is accessible from outside the network by trying to access it in the browser.

   

There are a few reasons why this might not work, here are some that we’ve seen:

• The external DNS record that points to the customer’s PaperCut server has been deleted or was changed.
• The customer updated their firewall or security appliance, which is now blocking or filtering the ports needed for communication (80, 443, 9191, or 9192 depending on what is configured).
• The “shared secret” is not configured identically in the PaperCut Payment Gateway properties file and in on the payment provider’s side.
• The Payment Gateway is configured to only allow post-back from specific IP addresses, but the Payment Provider IP address has changed. To troubleshoot and diagnose, look in the *.properties file for this specific Payment Gateway, and check for a line containing postback-allowed-ip=. If this is set to a specific IP, try changing it to a wildcard “*” to allow post-back from all IP addresses. You will need to save the file and restart the PaperCut Primary Application Server service for this change to take effect.

Collect the Payment Gateway Logs

To diagnose the problem, you may need to collect the How to collect Payment Gateway logs. Looking at the event.log we can see when the most recent successful transaction was, and looking at the transaction.log we can see if the PaperCut server is receiving the post-back from the payment provider to acknowledge that the user-submitted payment.

However, this is only one-half of the equation. In many cases, it’s necessary to look at the logs of the payment provider to understand what’s happening on their end and whether their system is able to contact the customer’s PaperCut NG or MF server.

Still have questions?

Let us know! We love chatting about what’s going on under the hood. Feel free to leave a comment below or visit our Support Portal for further assistance.