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.

Failed transactions

There are times when transactions fail with an error that states the following in the Logs > Application Logs section of the PaperCut Admin web interface:

This error is the result of a cookie not being passed as expected when a user is redirected from the PaperCut User web interface to the TouchNet portal. Updating the server.cookies.session.same-site option in the server.properties file is necessary to mitigate this issue.

The default value is blank which equates to lax and ultimately lets the browser initiating the request decide how to handle the cookie. When set to none as suggested below, this allows the cookie to be sent but does require that HTTPS is enabled and configured as only secure cookies are allowed.

The steps required are as follows:

• Stop the PaperCut Application Server service
• Open the server.properties file in your preferred text editor with administrator privileges. It’s located in the following directory where your Application Server is installed and running:
  [app-path]\PaperCut MF\server\
• Locate the following option (the default value is blank):
  server.cookies.session.same-site

• Update the value to match what’s displayed below:
  server.cookies.session.same-site=none
• Start the PaperCut Application Server service

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.