Uniprint Technote: Credit Card Gateway Integration

Pharos Uniprint offers an optional Credit Card Gateway that will allow a user to securely add funds to their Pharos account using their credit card, debit card, or PayPal™ account via the Pharos Print Center. To provide this feature, the Print Center integrates with the PayPal™ payment gateway service, which is one of the most widely used payment gateway services in the world today.

Overview

The Credit Card gateway is a separately licensable component of the Pharos Uniprint system that enables a user to add funds/money to their Pharos account using their credit card, debit card, or PayPal account to pay for their printing or copying services within the Pharos environment.

In previous versions, funds were manually added using Pharos Administrator or Pharos Remote and required the aid of a Pharos cashier or administrator or they had to walk to a Pharos kiosk or coin machine to add funds. With the credit card gateway, a user can add funds directly via the Pharos Print Center or Pharos Station (in Print Center mode).

While the organization needs to create a PayPal business account, users (e.g. students, staff, and guests) do not necessarily need their own PayPal accounts; they can use their credit cards or debit cards to add funds. Funds that are added via the credit card gateway are transferred to the Pharos user accounts immediately.

Credit Card Gateway Components

Component	Description
Pharos Print Center Services (Pharos API)	The Pharos API consists of the following components: Pharos Rest API - This component enables communication between the Print Center website and Print Services. It also allows PayPal to be connected with the Pharos system. Pharos Systems Payment Notification Processor – This service is responsible for processing approved PayPal transactions. It will credit the Pharos user accounts based on the details provided by PayPal. The Pharos Print Center Services (Pharos API) should be installed on the same machine as the Pharos Uniprint Print Services. The Pharos API on the Uniprint Print Server will need to be accessible by PayPal’s servers on the Internet. PayPal will initiate connections to the Pharos API service to complete transaction processing, so the Pharos API must be externally accessible. PayPal will connect to the Payment Notification Processor service on port 443.
Pharos Print Center Web	This is the website component that allows users to release their print jobs from laptops and traditional desktops to any Pharos controlled device.

Component

Description

Pharos Print Center Services (Pharos API)

The Pharos API consists of the following components:

Pharos Rest API - This component enables communication between the Print Center website and Print Services. It also allows PayPal to be connected with the Pharos system.
Pharos Systems Payment Notification Processor – This service is responsible for processing approved PayPal transactions. It will credit the Pharos user accounts based on the details provided by PayPal.

The Pharos Print Center Services (Pharos API) should be installed on the same machine as the Pharos Uniprint Print Services.

The Pharos API on the Uniprint Print Server will need to be accessible by PayPal’s servers on the Internet. PayPal will initiate connections to the Pharos API service to complete transaction processing, so the Pharos API must be externally accessible. PayPal will connect to the Payment Notification Processor service on port 443.

Pharos Print Center Web

This is the website component that allows users to release their print jobs from laptops and traditional desktops to any Pharos controlled device.

Credit Card Gateway Workflow

Here’s a step-by-step example of how the credit card gateway integrates with PayPal.

In the Pharos Print Center website, a user clicks the Add Funds button to add funds to his/her internal Pharos account. The Add Funds dialog box opens.
The user enters the desired amount and clicks the Continue to Payment button. The user is then redirected to the PayPal site (Payment provider) where they charge their credit card account or PayPal account. Deduction of funds from Credit Card is done by PayPal at the time – this will always happen regardless of whether the transaction makes it back to Uniprint or not.
1. The PayPal user is redirected to this path when they click the Add Funds button on the Pharos Print Center website: https://www.paypal.com/cgi-bin/webscr.
2. After funds have been deducted, the user is redirected back to the MyPrintCenter website: https://customerservername.domain/myprintcenter/. This redirection must be defined in the account setup with PayPal.com, please refer to the “Setting up PayPal Auto Return" section
After a payment is completed, PayPal sends notification of the transaction to Pharos Uniprint.
1. PayPal sends notification of the transaction to Pharos Uniprint. This notification comes from notify.paypal.com or ipnpb.paypal.com. The notification includes user’s payment information such as the name and the amount of funds added.
2. The notification goes to the Pharos API server, which handles PayPal transactions. The full URL of the Pharos API server is https://customerservername.domain/PharosAPI/paypal.
3. When an admin user updates the server name under the Pharos Transaction Processor field (in the System > System Settings > PayPal context) then the Pharos API server URL is updated in the Pharos Database.
Only the server name is visible on the Settings context; the full URL is not visible. The server name defined here must be resolvable on the public Internet to allow PayPal to successfully connect.
The Pharos API acknowledges receipt of the transaction information to PayPal.
The Pharos API then connects to PayPal after the transaction is received, to confirm that the transaction is real by using this URL https://www.paypal.com/cgi-bin/webscr. PayPal replies back that it is valid.
The Pharos API stores the IPN transaction in the SQLite database temporarily.
The Payment Notification Processor Service reads the SQLite DB for IPN transactions.
The Payment Notification Processor sends IPN message back to PayPal for verification using the same URL as step 3a. (This step occurs only when the 3rd step fails).
PayPal sends response as verified or invalid (This step occurs only when the 3rd step fails).
The Pharos Systems Payment Notification service processes all verified IPN transactions and then credits the user’s accounts in the Pharos Database. Once IPN transaction ID is inserted in the Pharos database then the IPN transaction record is deleted from the local SQLite database.

Endpoints

The following provides the PayPal and the Pharos Print Center components endpoints.

Communication	Endpoints
MyPrintCenter to PayPal	Live PayPal account: https://www.paypal.com/cgi-bin/webscr Sandbox : https://www.sandbox.paypal.com/cgi-bin/webscr
Redirection to MyPrintCenter	https://<customerservername.domain>/myprintcenter Server name must be externally accessible if website is to be made available outside site's local network. Otherwise unnecessary. The MyPrintCenter URL must be provided under PayPal business account to return to MyPrintCenter website. For more information, please refer to the Setting up PayPal Auto Return section.
PayPal to Pharos API	From: notify.paypal.com or ipnpb.paypal.com Our observations show that the notifications are sent from notify.paypal.com, but PayPal has confirmed that IPN notifications are sent from ipnpb.paypal.com. To: https://<customerservername.domain>/PharosAPI/PayPal The server name needs to be externally accessible.
Pharos API to PayPal	Live PayPal account: https://www.paypal.com/cgi-bin/webscr Sandbox: https://www.sandbox.paypal.com/cgi-bin/webscr
Pharos Systems Payment Notification Service	May require external access to repeat API-PayPal connection if APIs attempt fails. Otherwise, it just reads local SQL Lite DB, processes the PayPal IPN transactions and credits Uniprint user’s account.

Pharos Station: Print Center Mode

This section includes the behavior of the Pharos Station: Print Center mode when the Add Funds feature is enabled.

Add Funds behavior on Pharos Print Station: Print Center Mode with multiple PPC servers

It is possible to configure the Pharos Station (in Print Center mode) to use the PPC/API local to the station’s Print Server instead of the central PPC/API. This can be done by installing both Print Center Web and Pharos API on a print server machine and then configuring the Pharos Station’s Operating Mode to use Print Center – Station’s Print Server in Pharos Administrator.

Setting the Pharos Station to use its local Pharos API would keep most of the traffic local to the server and only go off the server to talk to the Pharos database directly or to other servers when required if there are jobs to list on those servers.

If you enable Add Funds at the Pharos Station: Print Center mode, all functions of the Pharos Station are managed by the local PPC/API, except for the completion of adding funds. In this case, PayPal will send the transaction information to the designated Payment Notification Processor API, not the station's local PPC/API. The Payment Notification Processor API will take care of updating the user’s balance. This is because that server must have a firewall exception to receive PayPal notifications.

With Add Funds enabled at the station, it is a good idea to use Group Policy to block printer access on the station machine.

Updating User Balance

SignalR is not used at the station for detecting changes to user's accounts/job lists. So when a user adds funds at the station, the station will poll for account balance changes for 20 seconds, then after that it will show a message that the user must manually refresh to see their balance updated.

Limitations

Electronic payments (e.g. eCheck) and PayPal Express Checkout integration are not supported.

Credit Card Gateway Prerequisites

You must have the following ready before configuring Print Center with the Credit Card Gateway:

A PayPal business account. You will need to create a PayPal business account for the credit card gateway to work.
Bank account details of the university (Optional). This is the bank account to which the funds added by the students will be transferred. If no bank account is added, the funds will be transferred to the organization’s PayPal account instead.
Uniprint license with Credit Card Gateway license. Without the credit card gateway component of the license, the Add Funds button will not be available in the Pharos Print Center website and users will not have the ability to add funds using their credit card, debit card, or PayPal account.
The Pharos Print Center Services (Pharos API) must be externally accessible to PayPal's servers on the Internet to allow PayPal to complete transaction processing. For information on various deployment scenarios, please refer to the “Technote Pharos Print Center Deployment Strategy” document.

Setting up a PayPal Business Account

The following section provides step-by-step instructions on how to set up a PayPal business account if your organization does not already have one.

Step 1: Select the payment solution type

Before you begin to create an account, you will need to choose which type of payment solution is suitable for your organization. PayPal offers different types of payment solutions:

PayPal Payments Standard
PayPal Payments Pro

Pharos recommends using the PayPal Payments Standard because it handles the Payment Card Industry (PCI) requirement in addition to not having monthly and setup fees. Take note however that with all payment solutions, transaction fees apply.

To give you an idea of how much PayPal charges, the following table shows the associated fees with each type of solution. For a list of comprehensive features of each payment type, follow this link https://www.paypal.com/webapps/mpp/compare-business-products.

Step 2: Sign up for a PayPal business account

Sign up for a PayPal business account. After you have successfully signed up to PayPal, you will receive a message to confirm your email address.

Step 3: Set up you bank account in PayPal

This is the bank account to which the funds added by the students will be transferred. If no bank account is added, the funds will be transferred to the organization’s PayPal account instead.

You must have the organization’s bank account details ready to complete this task.

Browse to https://www.paypal.com/us/smarthelp/article/how-do-i-link-a-bank-account-to-my-paypal-account-faq686 for instructions to link your bank account to your PayPal account.

Configuring the Print Center to connect to PayPal

After you have created and set up your PayPal business account, the next step is to configure the Print Center to connect to PayPal. This involves setting up the following Print Center and PayPal settings in the System > System Settings context of Pharos Administrator.

Print Center Hostname
Business Account
Default Funds Amount
Minimum Amount
Maximum Amount
Currency
Transaction Fees Responsibility
Transaction Flat Fee
Pharos Transaction Processor

For information on these settings, see the Print Center and PayPal settings in the System Settings topic.

Setting up currency codes in PayPal

The following section describes how to add currency codes to your PayPal account and how to set up the Pharos Administrator so that it matches the currency code configured in the organization’s PayPal business account. It also includes the error message that you might encounter if the currency code in PayPal does not match the currency code in Pharos Administrator.

Dealing with currencies other than US dollars

PayPal supports multiple currencies and allows choosing a single currency as the primary currency. However, the Pharos Credit Card gateway allows only a single currency in Pharos Administrator.

By default, the currency set up in the Pharos Administrator is US dollars (USD). If your organization is outside of the United States and you wish to change to the currency of your country of residence (PayPal requires to register your PayPal account in the country in which you reside), follow these steps:

In the System > System Settings > PayPal context of Pharos Administrator, configure your desired currency (e.g. NZD).
In the PayPal business account, add the currency that you have configured in Pharos Administrator among your accepted currencies on PayPal.

To add a currency to your PayPal business account:

Log in to your PayPal business account.
Select Money.
Click Add a currency.
From the drop-down list box, select the currency that you wish to add and then click on the Add a Currency button.

Currency code mismatch between PayPal and the Pharos Administrator

You have to ensure that the currency set up in the System > System Settings context of Pharos Administrator matches the currency code set up in your PayPal business account otherwise users will see an error message similar to the one shown below. The transaction will not be processed and no funds will be added to the user’s account.

In the following example, the currency setting in the Pharos Administrator is set to US and the PayPal currency code is USD.

For a list of the accepted currency codes in PayPal, refer to this PayPal website.

Setting up PayPal Auto Return

When users add funds from the Pharos Print Center, they are redirected to the PayPal website. If you wish to immediately redirect back to the Pharos Print Center after a user has completed a PayPal transaction, you must set up enable Auto Return and set up the Return URL in the organization’s PayPal account.

To set up Auto Return and Return URL in PayPal:

Log in to your PayPal business account.
Select Account Settings.
Select Website payments, and then click on the Update button next to the Website preferences option.
Enable Auto Return by clicking the On radio button and then enter the Pharos Print Center URL (e.g. https://servername/myprintcenter) under the Return URL field.

Encrypting IPN Transactions

Credit Card Gateway transactions are temporarily stored in a SQLite database. This database is stored in C:\ProgramData\PharosSystems\Pharos API\ by default.

To store the SQLite database in a different location, add the following registry settings under HKLM\SOFTWARE\PharosSystems\Pharos API.

As of Print Center 3.4, the Print Center installer no longer creates the ‘Database Location’ or ‘Database Password’ registry entries on fresh install. But on upgrade, if the value of database location is NOT a default path or if the database password is NOT empty then they are not changed.

Registry Entry	Description
Database Location	Shows the location of the SQLite database. This is typically in C:\ProgramData\PharosSystems\Pharos API\. The database location can be moved to a non-default location by adding the \Pharos API key and the ‘Database Location’ string entry with the new path. On restart of IIS and the Payment Notification Processor Service, a new database will be created in the new location defined in the registry.
Database Password	By default, the database password is empty which means that the SQLite database is not encrypted. If you want to encrypt the database then you will need to enter a password for this registry key. Follow these steps to set up the SQLite database password: Make sure that the SQLite database is empty. Stop IIS and the Pharos Systems Payment Notification Processor Service. Update the “Database Password” registry with the password that you wish to use. Delete the SQLite database. Start IIS and Pharos Systems Payment Notification Processor Service.

Registry Entry

Description

Database Location

Shows the location of the SQLite database. This is typically in C:\ProgramData\PharosSystems\Pharos API\.

The database location can be moved to a non-default location by adding the \Pharos API key and the ‘Database Location’ string entry with the new path. On restart of IIS and the Payment Notification Processor Service, a new database will be created in the new location defined in the registry.

Database Password

By default, the database password is empty which means that the SQLite database is not encrypted. If you want to encrypt the database then you will need to enter a password for this registry key.

Follow these steps to set up the SQLite database password:

Make sure that the SQLite database is empty.
Stop IIS and the Pharos Systems Payment Notification Processor Service.
Update the “Database Password” registry with the password that you wish to use.
Delete the SQLite database.

Start IIS and Pharos Systems Payment Notification Processor Service.

Offline Cases

Occasionally, the connection between the credit card gateway and PayPal may be temporarily lost, for example when the Pharos Systems Payment Notification Processor service host becomes unavailable for some reason.

The Pharos API must respond to every IPN message it gets, whether we take action on it or not. If we do not respond, PayPal assumes the IPN was not received and re-sends it. Further, PayPal continues to re-send the message periodically until our listener responds, although the interval between retries increases with each attempt. An IPN will be resent for up to four days, with a maximum of 15 retries.
If Pharos Systems Payment Notification Processor service is offline due to exceptional circumstances, the SQLite DB holds the transactions. The Payment Notification processor will process all unprocessed transactions when it comes back online.
If Pharos DB is offline due to network failure, the transactions will remain in SQLite DB until they are processed by the Notification processor.

Setting up Pharos Print Center on a Cluster

When configuring the Print Center on a Windows cluster, make sure that the Payment Notification Processor is added as a cluster resource. For instructions on how to do this, please refer to “Installing Server Components on a Cluster” section of the “Uniprint 9.1 Planning and Installation Guide”.

PCI Compliance Information

Pharos Systems International understands that organizations that store, process, or transmit cardholder data must meet strict requirements to be PCI compliant. PCI compliance specifically relates to the security and controls around the payment applications and cardholder data within the merchant’s IT environment. The Pharos Uniprint Credit Card Gateway is not a payment solution and at no time does Pharos Uniprint provide software or systems to handle, process, or store credit card data; therefore, the Pharos Uniprint Credit Card Gateway falls outside of the scope of PCI review. According to the PCI Security Standards Council, it is the merchant or service provider's responsibility to ensure that they are using only products that support compliance.

The Pharos Uniprint Credit card gateway solution is meant to reduce the merchant’s scope for PCI compliance by using a URL redirect e-commerce implementation. Customers using the Credit Card Gateway may be eligible for PCI SAQ A or SAQ A-EP, provided they meet the eligibility criteria of that SAQ.

It is recommended the merchant monitor connections and redirections between the merchant and a third party since the connections can be compromised. The merchant should ensure no changes have occurred and that the integrity of the e-commerce solution is maintained. The PCI Security Standards Best Practices for Securing E-commerce provides best practices for merchants on securing and monitoring redirections.

Resources

For more information about PayPal, please refer to the following websites: