Table of Contents
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
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 property is available:
| Configuration property | Description |
|---|---|
|
ext.webapi.callback.url-base |
The publicly accessible base URL, i.e.
When SavaPage is implemented as 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. Important: use |
Table M.1. Web API Callback Configuration Property
The Payment Gateway Plug-in is based on the Web API Callback Plug-in and uses
the /callback/payment URL path. The following
configuration property can be set by using the Config
Editor of the Admin Web App.
| Configuration property | Description |
|---|---|
|
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 M.2. Payment Gateway Configuration Property
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.
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.10.5, “Financial”, Section 3.10.8, “Transfer Money” and Chapter 8, Payment Web App.
Mollie is a Dutch payment provider that offers a single Web API for various payment methods, including:
-
Creditcard
-
PayPal
-
paysafecard
-
SOFORT Banking (Europe)
-
SEPA bank transfers (Europe)
-
Bancontact/Mister Cash (Belgium)
-
Belfius Direct Net (Belgium)
-
IDEAL (Netherlands).
Mollie supports the European Economic Area and Switzerland and accepts 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.
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.
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.10.5, “Financial” and Section 3.10.9, “Send Bitcoins”.
As a privacy and security measure a new Bitcoin address is generated for each payment[56]. 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.
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.
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.
[56] 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.