Koha, the full-featured open source integrated library system we use at Lancaster Seminary, added an integration for PayPal beginning with the 16.05 release in May 2016. This feature allows libraries to collect credit card payments from patrons through the OPAC. As a small library, we can only accept payments in cash or check at our circulation desk. Enabling the PayPal integration in 16.05 in April 2017 allowed us to extend the flexibility of paying by credit card to our patrons, and it has been working well ever since.
There are two blog posts by Jessie Zairo at ByWater Solutions about the PayPal integration. The first, PayPal Payments in Koha published in February 2017, was a helpful guide to me as I was setting up our integration for the first time. In June 2017, Zairo wrote and published PayPal Set up in the Business Portal for Koha Integration that explains the steps one would need to go through in PayPal to prepare the Koha integration.
The purpose of this blog post is to help fill in some of the gaps from Zairo’s posts and show how the PayPal integration works in a small library.
Setting up a PayPal account as a business
Our library already had a PayPal account that we use for our online book sale fundraiser. Too much time has passed between now and the time we opened that account, so I do not remember all the exact particulars of setting up that account. However, I have been able to come up with a few points for libraries who do not already have PayPal accounts. Here’s what you might want to know about PayPal:
A business account has to be linked to a person with a Social Security number (or other government issued ID number accepted by PayPal). People on your staff who might be most appropriate for this responsibility include anyone who is responsible for issuing payments to vendors up to the director of the library. If anyone on the library staff has a business credit card issued in their name, that person might also be a good candidate to be linked to the library’s PayPal account. It is probably a good idea to link the account with a staff member who is responsible for other accounts on behalf of the library. When there is a change in personnel, it will make it easier to remember and track all the accounts that need to be updated with the new staff member’s information.
PayPal needs to be linked to a bank account. This is used for transferring monies received as well as funding your PayPal account if/when you use it for purchasing. It is up to the individual library to determine what banking setup they are most comfortable with. For our purposes, because we are embedded within a larger institution with multiple departments, our business office opened a separate account for us to specifically link to PayPal. This offers greater security for the seminary’s funds and helps the business office monitor transfers to and from PayPal since this is the only purpose for this bank account.
PayPal will email you, so think about the email address you want to give it. We have found that it is good that these emails go to more than one person, so we have our PayPal account set up to send an email to a distribution list. This way, more than one person is aware when transactions are made or if there are any security alerts on the account. It just makes good fiscal sense.
The PayPal help center for businesses also has good information on the details of setting up an account: https://www.paypal.com/us/smarthelp/home?selectedExp=business
Setting up the PayPal integration in Koha
Aside from the account information you will need to supply to Koha to set up the integration and link it to your PayPal account, there is one key system preference that you can use to customize how you want PayPal payments to appear in Koha: PayPalChargeDescription. This system preference is a single line of text that is passed to PayPal. PayPal uses this text to populate its “Description” field for the charge. It is used primarily on the emails that PayPal sends to both the patron and the library to confirm that a payment was made.
Koha does not currently have a way of dynamically updating the description to match the PayPalChargeDescription with accountlines.description (unless I’m missing something and there is a way to do it with <<fieldnames>>?). Right now, our system preference is set to a static description as seen in the screenshot above.
When setting this system preference, the description needs to be generic enough to apply to all types of payments a library may receive yet descriptive enough that a patron will recognize it when they see the confirmation and check their PayPal account transactions.
The Patron Experience
We created this video (above) to help our patrons use the PayPal option in their library accounts. The most common confusion that patrons have when trying to use PayPal to make a payment is that the patron must select the charges they want to pay. Selecting the charges, done by checking a box next to the line items in the table, calculates the amount that Koha will be sending to PayPal. Without making a selection, the amount to sent to PayPal remains at $0 and the “Make Payment” button does not activate.
Once a patron selects what they want to pay, s/he clicks the “Make Payment” button. This takes the patron directly to PayPal. From here, they complete the transaction with a credit card and/or an existing PayPal account. Once the transaction is completed, PayPal sends two emails. The one sent to the patron looks like this:
The description in the email is supplied by the PayPalChargeDescription system preference in Koha. The merchant information is supplied by your PayPal account settings.
The library receives an email from PayPal that looks like this:
Again, the description matches the PayPalChargeDescription system preference. The buyer information is supplied by the patron’s PayPal account and does not include any Koha account information. In other words, this email only includes account information related to PayPal and does not include borrowernumber, patron barcode, or any other information that Koha uses to identify patrons.
Once the payment is completed in PayPal, the patron can also log in and/or return to their patron account page in Koha’s OPAC to see that the PayPal payment was applied to their account. The payment is applied automatically and the account balance is adjusted immediately (*see note). If a patron’s account balance was causing a hold on checkouts, that hold would be released when the PayPal payment is completed and applied – a real bonus for libraries with limited staff and/or high traffic and need to offer a level of self-service.
*Note: I can’t say exactly when during the process the actual payment post in Koha happens. I can report that we’ve never had a problem with incomplete payments being erroneously posted to Koha. My best guess is that Koha receives some kind of confirmation from PayPal when the payment goes through and posts the payment then. Someone with more time to dig into the code would be able to say for certain when and how Koha gets confirmation from PayPal to post the payment. If you are that someone, I hope you post a comment below to set me straight!
The Library Experience
The library can check and reconcile payments made through PayPal in a variety of ways. In the library’s PayPal business account, the transactions appear in the register by the payee’s PayPal account name:
Clicking on the payment, shows transaction details:
The transaction details include a lot of the same information as the email sent to the library, and also includes the PayPal fee (yes, PayPal charges you a fee for every transaction you receive).
Within Koha, the patron account table on the “Fines” tab shows the history of charge and payment:
The PayPal integration for Koha currently uses the Note field to indicate that a payment is made with PayPal. Diving into the logs shows that the transaction is completed in the OPAC and the patron’s borrower number is identified as the transacting librarian. For reconciliation purposes, a report can be run to identify all payments with the note “PayPal” during a time frame. I created this simple report and added it to the Reports Library on the Koha Wiki: https://wiki.koha-community.org/wiki/SQL_Reports_Library#PayPal_payments_collected_in_a_date_range
Final thoughts
We’ve been using PayPal to allow our patrons to pay with a credit card for nearly two years. We’re now running Koha version 18.05, and the PayPal settings have carried over through our migrations to 16.11, 17.05, 17.11, and 18.05. As we’ve grown accustomed to using it and as Koha has continued to develop, here are a few additional thoughts and words of wisdom about implementing this integration in a library.
Defining a PayPal payment type
Version 18.05 introduced the ability to define custom payment types. Until the PayPal integration for Koha undergoes further development/enhancement to utilize a payment type called “PayPal,” there is nothing in Koha that will automatically apply this payment type to a PayPal-initiated payment.
If you wish to collect PayPal payments from other parties who do not have access to a patron account and need to track those payments in Koha, a PayPal payment type may make sense. One theoretical scenario could be for libraries who check out all interlibrary loan requests to a single ILL account. If a borrowing library loses an item, the lost item fee would show up on the general ILL account but an invoice would need to be sent to that library. If the borrowing library then wants to pay with PayPal and/or a credit card, the easiest way is to send a request money link through PayPal. The payment received through PayPal can then be recorded in Koha using the PayPal payment type.
Note, if you’re recording PayPal payments in Koha that have been received via PayPal and not initiated by the OPAC, using a PayPal payment type would also be a way to differentiate between the payments made by patrons directly through the OPAC and these other types of payments. If you are wanting to reconcile payments recorded in Koha with your PayPal account transactions, the report linked above would need to be edited to include account lines with the PayPal payment type as well as account lines with PayPal in the notes field.
As with recording any type of payment in Koha, creating the payment in Koha simply records a transaction of monies received (or forgiveness applied) through means outside of Koha. There is not a way to initiate a PayPal payment within the staff client. The only way for a patron or any party to send money to the library via PayPal is through the patron account details in the OPAC or through a request money link that the library creates in PayPal and shares with the patron.
Refunding a patron
While we haven’t needed to do this, there might come a time when a patron needs to be refunded. Perhaps they paid a fee by mistake. Perhaps they paid a lost item fee and later returned the item. Whatever the case may be, there is a way to issue a refund. First, the refund would need to be issued in PayPal. In the transaction details view in PayPal, there is an option to issue a refund. This option is only available for 180 days and as long as the payment status is completed, pending, or cleared (see PayPal’s documentation for more information).
Once the refund is underway in PayPal, then go to Koha to post the refund to the patron’s account. If you’re issuing a full refund of a PayPal transaction, the entire transaction can be voided or reversed in 18.05. There is a development underway to remove the reverse option because void is cleaner. I have noticed that voiding a transaction makes it disappear completely off the patron’s account. If you still need to see the history of the original PayPal payment, it can be found in the system logs if you have those turned on.
Another option to post a refund or partial refund in Koha would be to add a manual credit to the patron’s account. We have had a lot of issues with manual credits in our library, primarily because in 18.05 they cannot be undone. (We’ve actually got some JavaScript in place to hide the manual credit tab in the staff interface!) That being said, it is an option that could be used if the need arises.
Refunds can get complicated. Some libraries have a policy that no refunds are ever issued. Just saying.
Disclaimer for multi-branch library systems
As the title for this post indicates, I’ve implemented Koha’s PayPal integration in a small library context. I cannot say how this would work in a library system with multiple branches or in a consortia catalog-sharing situation. If you, dear reader, are in one of those settings and have implemented the PayPal integration, please consider sharing your experience in the comments below. Others will likely find your insights to be very, very helpful.
