Appendix L. SavaPage Plug-ins

Table of Contents

L.1. Web API Callback Plug-in
L.1.1. Payment Gateway Plug-in

A plug-in (aka extension) is a software component that adds a specific feature to SavaPage. Plug-ins have a well-defined interface so partner developers can easily create isolated components that extend the application with new features. Extension interfaces are defined in the savapage-ext project.

A plug-in is installed by copying its property file in /opt/savapage/server/ext and its jar files in the /opt/savapage/server/ext/lib directory. For example, the Mollie Payment Plug-in is installed with these two files:

/opt/savapage/server/ext/savapage-ext-mollie.properties
/opt/savapage/server/ext/lib/savapage-ext-mollie-<version>.jar

Important

Since property files contain sensitive data make sure they are protected by executing commands like:

sudo chown savapage:savapage savapage-ext-mollie.properties
sudo chmod 600 savapage-ext-mollie.properties

L.1. Web API Callback Plug-in

The Web API Callback method is used by many third-party providers who offer their services via HTTP. SavaPage supports this method with the /callback URL path. However, URL protocol and authority for the callback needs to be configured. Configuration is done by using the Config Editor of the Admin Web App. The following configuration item is available:

Configuration itemDescription

ext.webapi.callback.url-base

The publicly accessible base URL, i.e. protocol://authority without the path, of the Web API callback interface (no trailing slash).

Since SavaPage is typically implemented as an intranet application to be accessed with a local URL, take care to configure proper port forwarding of the public base URL to the local SavaPage server host name or IP address in your router or firewall .

Table L.1. Web API Callback Configuration Item


L.1.1. Payment Gateway Plug-in

The Payment Gateway Plug-in is based on the Web API Callback Plug-in and uses the /callback/payment URL path. The following configuration item can be set by using the Config Editor of the Admin Web App.

Configuration itemDescription

ext.webapi.redirect.url-webapp-user

The User Web App URL used by the Web API to redirect to after a remote Web App dialog is finished.

Configuration is optional. SavaPage uses the local URL from which the remote excursion started as default.

Table L.2. Payment Gateway Configuration Item


Payment Gateway events are persisted in the rotating log file:

/opt/savapage/server/logs/paymentgateway.log

This file has a tab separated value (TSV) format for easy import and manipulation into spreadsheet programs.

L.1.1.1. Generic Payment Plug-in

A Generic Payment Plug-in implements several payment methods behind a single Web API. Only one generic plug-in can be active. See Section 3.9.3, “Financial” and Section 3.9.6, “Transfer Money”.

L.1.1.1.1. Mollie Payment Plug-in

Mollie is a Dutch payment provider that offers a single Web API for the following payment methods:

  • Creditcard

  • PayPal

  • Bitcoin

  • paysafecard

  • SOFORT Banking (Europe)

  • SEPA bank transfers (Europe)

  • Bancontact/Mister Cash (Belgium)

  • Belfius Direct Net (Belgium)

  • IDEAL (Netherlands).

Mollie supports EUR payments only.

See the README.md of the savapage-ext-mollie project for more information.

Note

The Mollie Payment Plug-in is shipped with the SavaPage install binary.

L.1.1.1.2. Generic Payment Pitfalls

Callback messages for generic payments return the identity of the user that started the payment in the Transfer Money dialog. So, when a payment is acknowledged, we can easily add the amount paid to the user's balance. In some very unlikely cases a user might not be found. For example, when a database export is restored or a user was deleted, all in the short lifecycle of a payment transaction.

In the rare case a user is not found, a warning message containing the user and transaction identification are written to the Application Log. With this information the user balance can be updated manually, after the user has been added again, either in the Admin WebApp or with a Server Command.

L.1.1.2. Bitcoin Payment Plug-in

The Bitcoin Payment Plug-in supports native Bitcoin payments with the advantage of a low native Bitcoin transaction fee. Only one Bitcoin plug-in can be active. See Section 3.9.3, “Financial” and Section 3.9.7, “Send Bitcoins”.

As a privacy and security measure a new Bitcoin address is generated for each payment[42]. Generated addresses are held in a Bitcoin wallet. The location and access credentials of the wallet are to be specified in the plug-in property file.

Note

When a Bitcoin payment method is active in an enabled Generic Payment Plug-in, it is deactivated in favour of an enabled Bitcoin Payment Plug-in.

L.1.1.2.1. Blockchain.info Payment Plug-in

With the Blockchain.info plug-in users can send Bitcoin payments to a Blockchain.info web-based wallet. See the README.md of the savapage-ext-blockchain-info project for more information.

Note

The Blockchain.info Payment Plug-in is shipped with the SavaPage install binary.

L.1.1.2.2. Bitcoin Payment Pitfalls

Because of the anonymous nature of Bitcoin payments, a callback message with a payment confirmation only contains the Bitcoin address and transaction hash as identification.

Fortunately, we can trace the identity of the user who made the payment, either by the one-time Bitcoin address, that we generated and reserved for the user at the start of the Send Bitcoins dialog, or by the Bitcoin transaction hash, that we linked to a user payment transaction at the callback of the first confirmed payment.

When a user can not be traced, the payment confirmation is ignored. This can happen when a database export is restored and either the user, the reserved Bitcoin address or transaction hash is missing from the database. This case becomes more unlikely as the number of confirmations after which the payment is trusted is set lower, causing a shorter latency of a trusted payment confirmation.

When a payment confirmation arrives for a Bitcoin address for which a user payment transaction link is present with a different transaction hash, it is ignored. This can happen when:

  • A user, against advice, reused the generated Bitcoin address, as offered in the Send Bitcoins dialog, to make an extra payment.

  • A payment from the Bitcoin Wallet was executed which lead to a transaction with a positive satoshi remainder.

When a payment confirmation is ignored, a warning message with the Bitcoin address and transaction hash is written to the Application Log. This information can be used to query the transaction history in the Bitcoin Wallet. Since the Bitcoin address is tagged in the Wallet with the user id, any transaction with a received amount can be used to trace the user. In case an extra user payment is identified, the user balance can be updated manually, either in the Admin WebApp or with a Server Command.



[42] As Satoshi Nakamoto, the elusive creator of Bitcoin, states in his Bitcoin whitepaper : ... a new key pair should be used for each transaction to keep them from being linked to a common owner. Also see this article on address reuse.