eCommerce

How do I set up fine payments in Aspen?

If using a vendor Aspen directly integrates with:

1. Select your vendor in Aspen Administration > eCommerce and fill in the required credentials. Read the section(s) on this page applicable to your payment vendor for more information.
2. Finish setup in Aspen Administration > Primary Configuration > Library Systems >  Fines/e-Commerce to configure payment settings. To learn more, head to the "Fines/eCommerce Setup in Library Systems" section on this page.

If using a vendor Aspen does not directly integrate with:

1. You have the option to link out to the external payment site. This will take users outside of Aspen to pay their fines and fees.
2. Navigate to Aspen Administration > Primary Configuration > Library Systems >  Fines/e-Commerce to configure payment settings.
3. Under Show E-Commerce Link, select "Link to ILS."
4. Under Pay Fines Link, enter the URL where users should be directed to pay their fines.

Updated 2023/01/26 - md bws

What setup is needed in our ILS?

If you already allow patrons to pay their fines with credit cards via your ILS, and you want to allow patrons to pay their fines from their account in Aspen, typically there is little or no additional setup needed on the ILS side. However, you will still need to be sure your eCommerce provider works with Aspen and is configured in Aspen. Read through the sections on this page to learn more about which vendors Aspen is compatible with and what setup is required in Aspen's settings.

When a fee is paid in Aspen via direct integration, Aspen will update your ILS with the payment information, which will clear the fee from their account. 

When a fee is paid in Aspen via a link to an external payment site, that site will update your ILS with the payment information, which will clear the fee from their account. The ILS will then update the user's account in Aspen. (If you do not see the fines/fees cleared from their account in Aspen immediately after paying on an external site, you may need to click the Reload button to force an update. Otherwise, information should update within 10-15 minutes.)

I'm migrating to Koha and Aspen supported by ByWater at the same time. How do we make sure we're set up?

After confirming your eCommerce vendor, your Aspen implementor will send a ticket with instructions to obtain your credentials. The Koha implementation team will have conversations to make sure you are set up on the Koha side, if you wish to allow staff to accept payments from patrons at the service desks.

Updated 2023-01-27 md bws

Within Aspen Administration > eCommerce, you will find settings for various payment integrations:

• ACI Speedpay
• Certified Payments By Deluxe
• Comprise
• FISERV SnapPay
• FIS WorldPay
• InvoiceCloud
• PayPal Developer
• PayPal Payflow
• Square
• Stripe
• Xpress-pay

To add the integration with the service you prefer, simply click on the one you want to set up and you will be presented with a form to fill out.

If you are uncertain of any information you're entering, contact the vendor to verify.

Example from Comprise:

Select the libraries who use this payment vendor credentials. If all libraries within the consortium use the same payment service, you can "Select All."

If you are not seeing all of these payment options, check your permissions in Aspen Administration > System Administration > Permissions > eCommerce and make sure you have the corresponding permissions.

See below for more information on specific ecommerce vendors.

Enable Payment History

To enable this, go to Aspen Administration > Primary Configuration > Library Systems > click into the Library System > Payment History > check Show Payment History for fine paid in Aspen.

Payment History will show any transactions run through Aspen Discovery - including fines/fees paid and donations from the ecommerce integration you have set up. This will not pull in transactions made via the ILS (i.e payments taken by staff via the ILS, credits, refunds).

Customizing the Payment History Message

The Payment History message is in Aspen Administration > Primary Configuration > Library Systems > click into the Library System > Payment History > Payment History Explanation

The Default message is "This page only reflects payments made through your online library catalog. If you have questions about payments made at the library in person or through other means, please contact your library."

Libraries can customize this message to explain to patrons how/what the Payment History is showing, how they can print it, etc.

Libraries can also add the message in various languages by tabbing across the languages they've added to their catalog. Learn more about adding languages.

Delete Payment History Older than (days)

In Aspen Administration > Primary Configuration > Library Systems > click into the Library System > Payment History > Delete Payment History Older than (days) libraries can set an amount of time that patrons can view their history.

The default is 0. 0 means do not delete and the transactions will go back as long as the ecommerce integration has been enabled in Aspen Discovery.

You may decide on something like a year (365). We suggest if you need something like a year for your records, to put in something a little over a year, exp: 375 days.

This is a rolling year and not a calendar year. 

Once the Payment History is deleted, it is deleted. There is no way to get it back. So, if you switch from 0 to 60 days and then decide you really want 365 days, there is not a way to get that history back.

User Experience

Once enabled, users will see Payment History in Your Account.

This screen can also work as a receipt or log for users.

More Details

Users can click on More details for each transaction and this will show the information that Aspen Discovery has available from each transaction. These details will vary by ecommerce vendor.

First, if you are using a payment vendor that Aspen integrates with via API, make sure your vendor credentials are set up in Aspen Administration > eCommerce. See the above sections for more specific information.

Next, from Aspen Administration, navigate to Primary Configuration > Library Systems > click into the library system > Fines/e-Commerce to finish configuring payment settings. 

Show E-Commerce Link: Select your payment processing option from the following:

Note: If you are not accepting online payments, you'll want to make sure this is set to "No Payment." 

If you are accepting online payments with a vendor Aspen does not integrate with at this time, you may link out to an external payment site. In this case, select "Link to ILS."

Which Fines Should Be Paid?: Select which types of fines can be paid via Aspen.

• All Fines: The user must pay the full total of fines/fees all at once. (No partial payments)
• Selected Fines: allows users to choose with a checkbox which fines they would like to pay.
• Partial payment of selected fines: allow users to choose with a checkbox which fines they would like to pay AND allow them to type in a portion of that amount to pay.

Fine Payment Order by type (separated with pipes): Enter which types of payments you would like to accept before others, if applicable. In this example, the library has chosen to prioritize Account Management, Lost, and then Overdue.

Pay Fines Link: The default link where users are sent to make payments will be {yourAspenURL}/MyAccount/Fines unless you set the URL to something else. If you want to link users out to an external fine payment site, enter that URL in this field.

Pay Fines Link Text: The default text that shows to patrons will be "Click to Pay Fees Online." If you'd like this link to say something else, enter that text here.

Minimum Fine Amount: To avoid paying credit card processing fees on small transactions, libraries can choose a minimum fine amount to process. For example: setting a minimum of something like $5 to avoid paying the processing fee on someone's 0.25 cent fine transaction.

In the below example, the user owes $15 and the library has set the Minimum Fine Amount to $20. As a result, the user will not see the Click to Pay Fees Online option until they have reached at least $20 in fines.

When the user clicks into My Account > Fines and Messages, there will be no option to pay and there will be a default message about the library's minimum amount. The default notice is "Fines and fees can be paid online when you owe more than {minimum fine amount}." This allows users to still see their fines and fees, even if they can't pay them.

Show Refresh Account Button: Whether or not a Show Refresh Account button is displayed in a pop-up when a user clicks the E-Commerce Link. This will allow the patron to refresh their account so that they can see any updates to fines paid.

Convenience Fee: If you charge a flat convenience fee to patrons paying online, you can provide that amount and Aspen will include it when displaying fines. This is only for display and patrons will not be charged this additional fee outside of what is configured with your eCommerce vendor.

Terms of Service: In this box you can include any information about your online payment policies.

This is how this will display in the patron account:

{Vendor} Settings: The next several sections are tied to each set of settings. From the dropdown of the payment vendor you are using, select the corresponding set of settings. 

Symphony Payment Type: Symphony libraries can define how the payment comes through to the ILS with this field. By default, payments made through Aspen will show as CREDITCARD, but you can use whatever you need in this field instead (such as PAYPAL or ASPEN, for example).

For consortiums, Aspen can support different payment options per library system. These can be set up in Aspen Administration > Primary Configuration > Library Systems > click into the system to edit > Fines/e-commerce.

Another thing to consider when setting up multiple accounts is which library receives the payment if a patron uses multiple libraries. This is a global setting (one choice per server/consortium) and can be configured in Aspen Administration > System Administration > System Variables > Library to use for fine payments.

By default, this is set to Patron Home Library.

Example: The home library on my account is Main Library. I have overdues and replacement costs from East Library and Main Library on my account. When I pay in Aspen, regardless of whether I am using the East Library catalog or the Main Library catalog, my money is processed through Main Library.

The other option is Active Catalog.

Example: The home library on my account is Main Library. However, I work closer to East Library and navigate their catalog (east.aspendiscovery.org) the most. I have overdues and replacement costs from both East Library and Main Library on my account. I log into east.aspendiscovery.org and pay all of my fines. My money is processed through East Library.

Updated 2023/01/26 - md bws

The eCommerce and Donations reports will display payment information for fines and donations, respectively.

eCommerce Report

• Payment Type: Payment type
• Transaction Date: Date of transaction
• Transaction Type: The kind of transaction it was
• User: The user who made the payment
• Paid From: The interface used when making the payment
• Library: The patron's home library
• Order ID: The ID of the order within the payment system
• Transaction ID: The ID of the transaction order within the payment system (if different from the order id)
• Total Paid: Amount paid
• Fines Paid: The ID of the order within the payment system
• Completed?: The payment processor accepted the transaction
• Cancelled?: The user cancelled the payment
• Error: If we got an error back from the payment processor or if we got an error updating the ILS
• Message: A message returned by the payment system

Filter Report

Filters can be applied to the eCommerce Report, like Transaction Date - After, Before and Between - to better view the available data.

Export eCommerce Report to CSV

Information can exported to CSV for either all the information that you see on the screen by clicking Export to CSV or you can select individual rows to export by clicking on Export Selected to CSV. Any filters applied will be retained in the export. Only the columns available on the screen will be exported. Aspen has a limit of 1000 rows in the export. 

Permissions

To restrict the eCommerce Report to certain library systems/locations, you can give Library Admin these permissions

• View eCommerce Reports for Home Library
• View Donations Reports for Home Library

To set up ACI Speedpay, you will need to fill in credentials here.

Reach out to ACI Speedpay for credentials. 

To set up Certified Payments By Deluxe, you will need to fill in the following settings:

To set up Comprise in Aspen, fill in the following fields:

Note: The Customer ID field must be a number with no special characters.

Important information for working with FIS WorldPay. 

Aspen needs FIS to setup the following fields:

• UserPart1 as Payment ID (this is the minimum required field)
• UserPart2 for Patron’s First Name
• UserPart3 for Patron’s Last Name
• UserPart4 for Patron’s catalog username/barcode

The production and test URLs also need to be sent to FIS to be whitelisted on their firewall before payments will go through.

In eCommerce > FIS WorldPay Settings, add:

• Merchant Code
• Settle Code

Note: The Merchant Code and Settle Code look very similar and are often a combination of letters and numbers - exp: 00LIB-LIBRA-LIBXX-00

• Payment Site URL (This URL might look like this: https://paydirect.link2gov.com/{libraryname})

When setting up InvoiceCloud, libraries can add a Credit Card Service Fee to help with the processing costs from the library. This will charge this fee to every transaction.

As of the 24.06 release, NCR Payments is available via Aspen Discovery.

To set up, go to Aspen Administration > eCommerce > NCR Payment Settings > Add New

Name your settings: i.e. NCR - Main Library

You will need these credentials for each account you are setting up:

• Client Key
• Web Key
• Payment Type ID (typically 1)

You may need to reach out to NCR for these credentials and help setting up the correct page. 

Then, select the corresponding Libraries to publish this integration to and Save.

Complete eCommerce set up in the Library System settings.

User Experience

Once set up, users with fines will see the Click to Pay Fines Online button.

It will redirect them to a customized page to finalize their payment.

Users will need to click Make Payment to process the payment.

Users will see a Payment Completed screen.

This PayPal integration uses PayPal's REST-APIs (https://developer.paypal.com/api/rest/).

Note: This is not the same as PayPal Payflow. There are a separate set of settings for PayPal Payflow

Your PayPal settings can be added at any time during implementation. To add the integration, you will need to get your Client ID and Client Secret.

Get Information From PayPal:

Step 1: Log in to https://developer.paypal.com

You will need:

• Client ID
• Client Secret
• Email address where any payment errors should be sent

Once you have the credentials, enter them in Aspen Administration > eCommerce > PayPal Settings. 

Next, set up configurations in the corresponding Library System in Aspen Administration > Primary Configuration > Library Systems > Fines/ e-commerce.

Make sure the Show E-Commerce Link is set to PayPal and the PayPal Settings are set to your live scope.

Testing with PayPal Sandbox

Note: Testing is no longer available with live API credentials. In order to test fine payments without real transactions being posted, you'll need to set up a sandbox environment using the instructions below.

In order to test paying fines in Aspen, you'll need to use sandbox credentials instead of live credentials. This requires a unique set of sandbox credentials from your PayPal account, and tied to these sandbox credentials are sandbox credit card information. 

Below are the instructions for obtaining PayPal Sandbox credentials, both the client ID/secret and testing CC info. Using any other credit card information with the PayPal Sandbox account will produce errors.

Step 1: Log in to https://developer.paypal.com

Now, to obtain your corresponding sandbox credit card info:

Once you have entered in the Sandbox credentials into Aspen and tested the functionality to your satisfaction, you must go back to retrieve your Live paypal credentials and enter those into Aspen instead. Finally, make sure that "Use Sandbox Mode" is not checked in Aspen Administration > eCommerce > PayPal Settings.

Updated 2024-05-09 - km bws

PayPal Payflow

If you are using Payflow with your current ILS, you will need to create a new PayPal Manager account with Payflow in order to integrate PayPal Payflow prior to going live with Aspen.

Aspen is only able to integrate with Payflow Link. Payflow Pro is not available.

If you want to test Payflow transactions prior to activating your account, you will need to keep your new account in TEST mode. You will still need to go through the setup instructions in this section, but do not activate your new account until you are ready for Aspen to process live transactions.

Please refer to "Testing in Sandbox Mode" at the bottom of this section for more instructions.

Otherwise: set up your account as needed, making sure the account is activated, and follow these instructions. 

Payflow Credentials for Aspen Discovery

You will need the following credentials from your PayPal Manager account:

• Partner ID (Partner)
• Merchant ID (Merchant Name)
• User
• Password

To create a new PayPal Payflow setting, visit Aspen Administration > eCommerce > PayPal Payflow Settings and Add New.

The Partner ID and Vendor ID are typically what you use to log into PayPal Manager. You can verify these credentials in your PayPal Manager account by going to Account Information > Contact Information > Company Information.

To get the User and Password, continue following these instructions.

Setting up the Payflow User and Password

1. Log into PayPal Manager.
2. Click Account Administration > Manage Users.
3. Click Add User.

4. Under Admin Confirmation, you'll need to confirm this action by entering the password for your default admin user.
5. Under User Information, list the contact name and email of a staff user who should receive notices related to this account.
6. Under User Login Information, set up the login name and password you want to use for integration with Aspen. The login name could be something self-descriptive like "AspenDiscovery"
7. Under Assign privilege to User, select "API_FULL_TRANSACTIONS" for the predefined role, and "Active" for the user status.

8. Click Update to complete this setup.
9. Enter the user login name and password you created into the Payflow settings in Aspen Discovery.

Setting up the Checkout Page

You must set up a checkout page for use with the Aspen Discovery integration. 

1. Log into PayPal Manager.
2. Click Service Settings > Under "Hosted Checkout Pages," click Customize.
3. Select Layout C, then click Save and Publish.

Next, verify the settings for the hosted checkout page.

1. Click Service Settings > Under "Hosted Checkout Pages," click Set Up.
2. Leave the boxes unchecked in the Billing Information section.
3. Under Payment Confirmation > Enter Return URL, type in your Aspen catalog URL with /MyAccount/Fines at the end. (Example: library.aspendiscovery.org/MyAccount/Fines)
4. Under Payment Confirmation, make sure Return URL Method is set to GET.
5. Under Silent Post for Data Transfer, switch Use Silent Post to "Yes", check the box for "Void transaction when my server...", and make sure the two URL fields are empty.
6. Under Email Confirmation, you can set up any email confirmation you'd like to send to your patrons.
7. Under Security Options, set AVS and CSC to "No" and switch Enable Secure Token to "Yes"

PayPal Express

PayPal Express does work with the Pay Flow integration. Enabling Express will add the "Check out with PayPal" option to the payment modal:

PayPal Credit

This functionality does not work with Aspen's Pay Flow integration at this time. Please ensure this is disabled in Pay Flow settings.

Allowed IP Addresses

If you have everything set up and your transactions will still not go through, you may need to make sure that your Aspen server IP is one of the allowed IP addresses in your PayPal Manager account.

1. Go to Account Administration > Manage Security > Allowed IP Addresses for API
2. Either blank out all IP addresses, or make sure your Aspen server IP is enter in.
3. Click Update after making changes, then try to make a payment again.

Once enabled, the modal will look something like this:

If you are seeing a PayPal Credit option, we suggest turning it off as we do not currently support PayPal Credit and the option stretches the payment modal.

To turn it off, Log in to PayPal Manager > Click Service Settings > Click Hosted Checkout Pages > Select Set Up > Under PayPal Express Checkout, select No for Enable PayPal Express Checkout and No for Enable PayPal Credit > Click Save Changes.

Testing in Sandbox Mode

If you choose to test in sandbox mode, ByWater is only able to provide limited troubleshooting assistance. If possible, we recommend using an activated account with live transactions to ensure your credentials are entered correctly and the integration is working.

In PayPal Payflow settings in Aspen, check the "Use PayPal Payflow Sandbox" checkbox. Aspen's sandbox mode will only work when the PayPal Manager account is in TEST mode (not activated). 

In addition to all of the setup instructions outlined above, you will also need to disable Fraud Protection during testing. To do this, click Service Settings > Fraud Protection > Test Setup > Edit Standard Filters. Uncheck all boxes on the left column, then click Deploy. It can take an hour or more for these changes to propogate. If you attempt to test transactions too soon, your test transactions will be declined and flagged as fraudulent activity.

Once your test account is prepared, you will need to use specific card numbers for testing. You can find those numbers in Payflow's testing documentation. For the expiration month and year (MM/YY), use any month/year in the future. 

The provider page is here: https://developer.fiserv.com/product/SnapPay

Aspen connects to the Hosted Payment Page (HPP) method.

The terminology used in Aspen might not be a 1-to-1 match to the terminology used by the vendor.

API Authentication Code, for example, might be known as Secret or Key.

The settings in Aspen are in Aspen Administration > eCommerce > SnapPay Settings.

To begin, go to https://developer.squareup.com/us/en

Sign in with your already existing Square credentials or Create an Account and walk through the initial set up.

In the Applications section, hit the + sign to begin the process

Give your Application a name. Skip through the next modal screens.

Once completed, you will be taken to a set of Sandbox and Production Credentials

You will need the Application ID and the Access token

Next, you will need the Location ID.

On the left side menu, click on Locations.

You should see your Location(s) set up. If not, they are pulling in from https://squareup.com/dashboard/locations. 

You will need the Application ID, the Access token, and the Location ID for Aspen.

You can enter those in Aspen Administration > eCommerce > Square Settings > Add New.

If you are planning on using the Sandbox credentials and/or the Square Sandbox mode in Aspen, be sure to switch to Production Application ID and Token and/or uncheck Use Square Sandbox prior to going live. These settings are for testing payments only and does not collect money.

Once enabled, users will see a Payment design like this:

To sign in, go to https://dashboard.stripe.com

If this is the first time setting up a Stripe account, you'll need to walk through the steps to set up your account:

For Aspen, you will need the Public Key and the Secret Key from Stripe.

These can be entered in Aspen Administration > eCommerce > Stripe Settings > Add New

Stripe offers a test set of credentials that you can plug in to try the connection before going live.

If you are going to use the test set of credentials, be sure to switch over to the active credentials prior to going live or you will not receive the funds.

To find your test and production credentials, click on Developers > API keys and find your credentials.

To set up Xpress-pay, the following information must be filled out:

To add the option for patrons to make donations:

Go to eCommerce > Donations Settings and click Add New.

Libraries can choose from the following options:

• Allow users to select a specific branch to send their donation to
• Allow users to choose an earmark for their donation
• Allow users to make their donation in dedication of someone
• Allow users to enter their address when making a donation

Then, libraries can set the Page Contents of the form in the text box. 

In the next box, libraries can configure an Email Template to send a thank you for the donation.

The Page Content box will show at the top of the Donation form:

In the Donation Values, you can set preset donation amounts. 

These amounts will show like this on the Donation Form:

In the Donation Earmarks section

The Donation Earmarks will show on the Donation form as a dropdown menu.

In Donation Dedication Types, you can add Labels such as In honor of or In memory of.

These will show up on the Donation form when a user checks Dedicate my donation in honor or in memory of someone. Honoree information will expand and show the Donation Dedication Types and information on the honoree. 

Select the library or libraries for which these donation settings should apply.

On the Donation form, users can check Notify somone about this in memory or in honor of gift. This will expand Notification party information. 

At the bottom of the Donation form, the user can put in their first and last name.

Users can also choose Don't show my name publicly. 

If users add an email address, they can be emailed a receipt.

Once you've configured your donations settings, you can view the donations page at:

{yourlibrarycatalogURL}/Donations/NewDonation

When linking to this page from within Aspen -- for example, in a menu link -- you can simply link to /Donations/NewDonation and Aspen will automatically fill in your library's catalog URL. This will also ensure that your link will work even if your catalog URL changes in the future.

To locate the Donations Report go to Aspen Administration > eCommerce > Donations Report

The Donation Reports can be filtered at the top from a number of filters.

The Donation Report includes the following fields:

• Id: Numerical assignment after transcation
• Date Completed: The date the donation was completed
• First Name: First name of person making donation
• Last Name: Last name of person making donation
• Email: Email of person making donation
• Anonymous: Will be checked if the person making the donation would like to remain anoymous
• Donate To: Library location or branch donation is to go to
• Donation Amount: Amount of donation
• Donation Completed: Confirmation of transaction completion
• Earmark: Specific program or initiative funds should be donated to
• Dedicated? Will be checked if donation was dedicated to someone
• Dedication Type: If they have selected to donate money in someones honor or memory; 1 is yes
• Honoree First Name: If Dedication Type is selected, this will contain the first name of honoree
• Honoree Last Name: If Dedication Type is selected, this will contain the last name of honoree
• Notify someone of gift?: Whether or not the donor wants someone to be notified about this gift
• Notification Party First Name: The first name of the person to notify of the donation
• Notification Party Last Name: The last name of the person to notify of the donation
• Notification Party Address: The address of the person to notify of the donation
• Notification Party Address - City: The city of the person to notify of the donation
• Notification Party Address - State: The state of the person to notify of the donation
• Notification Party Address - Zip: The zipcode of the person to notify of the donation