External System and Integration APIs

The following API documentation is provided to support system integrators wishing to undertake development to hook PaperCut in with other systems. Reasons for considering integration include:

• Real-time integration with other accounting and/or payment systems.
• Replace the balance in the PaperCut database with a value hosted in another system.
• Allow users to transfer funds from one system to another.
• Integration with stored value cards or campus “one card” solutions.
• Integration with commercial payment POS systems already in place in the organization.

APIs are primarily presented as Web Services approach using XML-RPC as the preferred format. Recently some APIs have been also been exposed in a REST form (JSON and XML). Example code and wrapper classes are provided for many leading programming languages.

These integration options are possible using one of the following options:

Option 1 - Public APIs (Inbound APIs)

These XML web services APIs are included as standard with PaperCut and have no additional costs or certification requirements. They are open, supported and fully documented. For example the APIs can be used to “push” funds (i.e. transfer) from an external source into a PaperCut account. See the Inbound API documentation and the api.adjustUserAccountBalance call for more details. Helper utilities and example source code in C#, Java, Python, PHP and Ruby is provided.

The web services APIs are also available via a command line scripting tool, server-command. This method is ideal for usage from batch files, shell scripts and cron jobs.

All public APIs are open, documented and free to use by either PaperCut administrators, system integrators or middleware developers.

You can find some examples in our GitHub repository.

Account Recharge System (Manual Payment Gateway)

An in-house system for re-charging a user’s PaperCut account can be implemented using the public API as follows:

• A Custom Link in the user web page is used to link to your in-house payment recharge page.
• The user enters the amount to recharge and your system calls api.adjustUserAccountBalance to adjust the PaperCut balance.
• The user is returned to the user web page and sees the new balance displayed.

Option 2 - Print Scripting API

A popular option for extending PaperCut’s behaviour to implement tasks such as print routing, redirection, print policies, etc. is to use the Print Scripting Feature. Print Scripting offers a rich range of APIs and these can be used to implement many print workflow automation tasks.

Option 3 - User Directory Integration APIs (Advanced)

Organizations wishing to replace PaperCut’s LDAP/AD/eDiretory/OpenDirectory user direction support with a custom user directory provide may do so using a Custom User Information Directory Provider. This takes the form of an external command-line process designed to output data in a prescribed format. More information, including references to example code can be found in our case study.

Option 4 - Standalone Cash Loader and Kiosk API (Advanced)

There is an advanced internal web services API specially designed for smart cash loading devices such as vending hardware and kiosk stations. This API is only available for PaperCut MF. It offers:

• The ability for the device to register itself with PaperCut.
• The device appears as a “device” in PaperCut offering configuration from the web interface.
• The status of the device can be monitored from PaperCut.
• There is a separate dedicated transaction log and associated reconciliation reports.

Please contact support for details. A small licensing fee applies to enable this API. All implementations also need to be certified by PaperCut.

Option 5 - Vending API in the Release Station and/or Pay Station (Advanced)

This API is targeted at simple cash or stored value card equipment that can connect to a computer via a USB or serial cable. It allows vendors to connect their devices as funds sources into the PaperCut for:

• Pay and Release: Users can pay cash and release jobs at a release station.
• Pay Station: Users can put funds into PaperCut using the release station software running in Pay Station mode.

An overview of the pay/release station software (including screenshots) is provided in the PaperCut MF tour section Cash Payment Hardware.

Please contact support to discuss the API access, development licenses, and functional requirements. Customers using devices that integrate via this API will need to be running PaperCut MF and purchase a Pay Station license or entitlement for each device. All implementations also need to be certified by PaperCut.

Option 6 - Copier Terminal and Controller API

There is an advanced internal web services API specially designed for smart hardware copier terminal devices (copier controls) that can track and/or restrict copying, allowing copies to be reported to PaperCut for tracking and charging. This API is only available for PaperCut MF. It offers:

• The ability for the device to register itself with PaperCut.
• The device appears as a “device” in PaperCut offering configuration from the web interface.
• The status of the device can be monitored from PaperCut.
• There is a separate dedicated job log showing jobs tracked by the device.

Please contact support to discuss the API access, development licenses, and functional requirements. Each site using the implementation must pay a small licensing fee applies to enable the APIs (a Copier Controller Terminal license/entitlement). All implementations also need to complete a set of test cases to be certified by PaperCut and vendors are required to offer quality assurance commitments (to ensure compatibility is maintained over time).

Option 7 - Device REST API (for Device SSO)

This API allows 3rd party applications to query PaperCut for the list of connected external devices (e.g. MFPs running embedded software, hardware terminals, etc). This API allows the callers to determine the user logged into the device. This can be used for Single Sign-on for other 3rd party applications (e.g. embedded scan applications).

Please contact support to discuss the API access, development licenses, and functional requirements. Vendors should offer quality assurance commitments (to ensure compatibility is maintained over time).

Option 8 - Custom Top-up on Demand Payment Gateway (Advanced)

A top-up on demand payment gateway credits a user’s balance in real-time with the amount needed to fulfill a print job. PaperCut offers top-up on demand payment gateway integrations with several popular third party payment systems (see Payment Gateway Tour page.)

PaperCut also provides an API for system integrators to develop a custom in-house top-up on demand payment gateway. This API can be used to address most situations where customers wish to use an external system to automatically provide credit for printing or copying with no user intervention.

Option 9 - Outbound External Account API (Advanced)

IMPORTANT: This API is now deprecated and no longer supported for new developments This information is provided for historical users.

Alternatives, such as Option 1 and Option 8 above offer a better solution for most customers.

The External Account Source API allows 3rd party system integrators to develop interfaces to instruct PaperCut to use an external source for account balances (i.e. replace the balance in the PaperCut database with a value hosted in another system in real-time).

Option 10 - Intranet integration via gadgets/widgets and AJAX

A simple set of AJAX widgets and JSON based REST APIs are avaliable to assist with basic Intranet integration. See:

PaperCut Gadgets/Widgets

Option 11 - Hold/Release Queue and Release Station API

A rarely used API, this can be used to list, release and cancel/delete print jobs from hold/release queues, in addition to basic user authentication.

Please contact support to discuss the API access, development licenses, and functional requirements. Vendors should offer quality assurance commitments (to ensure compatibility is maintained over time).

Certification

Several of the APIs above make reference to the certification process. This is explained here. Details are also available regarding PaperCut’s Certified Integration Technology program, for certifying solutions that integrate with PaperCut.

See also

• Looking up card numbers in an external database
• Full list of 3rd Party Integrations.