Configuring the EPayment Library

MidCOM 2.4 ships with a component that allows for the electronic processing of payments in the system. It is based on a plug-in architecture and can thus be flexibly extended to support new providers. Bundled with 2.4 is only a single provider, the Solo" Market ePayment interface of the Finnish Nordea bank. The n.n.orders component is integrated with this library. Missing yet is a short tutorial on how to configure the payment library, so here we go.

General configuration

n.n.payment is configured like any other MidCOM: The snippet /sitegroup-config/n.n.payment/config must hold all neccessary information. The only relevant piece here right now is the payment provider specification, which controls what epayment plugin(s) may be used.

It is possible to have more then one payment option available simultaneously, even several instances of the same plugin (where it does make sense).

The configuration key handlers must contain the list of payment handlers that should be available to the user. It is an accociative array indexed by an handler name (string), which is a user-selectable, arbitary identifier for the given handler. The value of the handler is in turn a configuration array, which defines the properties of the handler.

Only one configuration option is shared throughout everything: The key _handler contains the name of the ePayment backend plugin to use for this particular instance, this is the filename of the plugin in the handler directory of the n.n.payment library, without the extension. The Nordea handler for example is called nordea.

The configuration settings are completly documented in the MidCOM API Documentation, package net.nemein.payment. Information written there always has precedence over the information in this short tutorial.

Terminology

Nordea Backend configuration

This backend implements the Nordea ePayment API documentation. The configuration parameter names match the form data group as presented in Chapter 3 of the Nordea Nordea ePayment API documentation as far as possible.

Implemented is the protocol version 0003, which uses HTTP GET/POST as an interface between the client and the server. It does only suport message digest ("MAC verifier") protected communication, to keep a maximum security standard.

Mandatory configuration settings

Optional configuration settings

The importance of the Reference Number Suffix

Nordea uses so-called "Reference Numbers" to identify each payment. You might want to have these numbers to be unique over all transactions being made. Unfortunalety, the Nordea API is rather restricted and old-fashioned, with reference numbers being limted to 20 numeric digits including one checksum digit.

Coming from this limitation, there is the need to allow for different sites using the same payment account. At this time, n.n.orders uses the Event ID as a reference number therefore. To ensure uniqueness, this suffix is appended to the number always to create unique "namespaces" for each instance of the payment system.

Note, that this solution is rather volatile, but it is right now the only way to ensure proper operation over multiple installations at once. It is recommended to assign two-digit suffixes here (e.g. 10-99).

With MgdSchema, this will probably be superseeded on the long run by having a centralized "payment transaction database", but until then we unfortunalety have to live with these limitations.

Be aware, that multiple transaction numbers do not prevent processing, as the identifier protecting a payment against multiple payments (user clicking submit twice etc.) is based on both the current UNIX timestamp and the reference number and should therefore be fairly unique (albeit still limited to 20 digits so there could, in theory, be clashes with large order numbers).

Example configuration

The following excerpt is an example configuration directly usable, it accesses the Nordea Test account so it can be safely used to test the payment plugin. All optional parameters are commented out but have valid options nevertheless:

'handlers' => Array
(
'nordea-test' => Array
(
'_handler' => 'nordea',
'SOLOPMT_RCV_ID' => '12345678',
'MAC_SEED' => 'LEHTI',
// 'SOLOPMT_RCV_ACCOUNT' => '29501800008512',
// 'SOLOPMT_RCV_NAME' => 'Testing',
// 'SOLOPMT_LANGUAGE' => 3,
// 'SOLOPMT_REF_SUFFIX' => '15',
)
)

Configuring net.nemein.orders

Activating support for n.n.payment in n.n.orders is quite trivial: Go into the component configuration of the topic in question and set the options Enable payment management functions and Enable electronic payment through net.nemein.payment to enabled.

BLOB Preview