• MidCOM 2.4
• TODO
• Baseclass: Component Interface
• Configuring the EPayment Library
• Execution of arbitary scripts
• Metadata Interface
• NAP changes
• Reworked Configuration Management
• The MidCOM Indexer
• Unified MidCOM configuration system
• Upgrading Installations
• Midgard Components Technical Notes

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

• A payment provider is a company providing a general service for online payment. A plugin provides an implementation for this.
• A handler is a concrete instance of a payment provider plugin, that provides payment services for a website.
• The service provider is the entity providing the payment services on his website to end-users.
• So, the end-user is the one that uses the payment handlers on a website to purchase some service or good from a service provider.
  

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

• SOLOPMT_RCV_ID: The ID number of the service provider that supports the Nordea web services.
  
• MAC_SEED: Message authentication code seed (also called "Service provider's MAC") which is used to compute and verify messages sent back and forth between Nordea and the service providers website. (See the fields SOLOPMT_MAC and SOLOPMT_RETURN_MAC in the Nordea ePayment API documentation for details.)

Optional configuration settings

• SOLOPMT_RCV_ACCOUNT: Account number that is used in the transaction, if different from the default account number of the service provider.
  
• SOLOPMT_RCV_NAME: Service provider name, if different from the default account number of the service provider.
• SOLOPMT_LANGUAGE: Language to use in the Nordea interface. If omitted, autodetection is attempted which is recommended as autodetect ties the remote interface as good as possible to the local site language. Possible values are 1 for Finnish, 2 for Swedish and 3 for English. English is the default fallback for all on-site languages except Finnish and Swedish.
  
• SOLOPMT_REF_SUFFIX: An integer, which will be appended to the reference number, in case you need to separate different systems from each other. This is unset by default, which means that the Reference is constructed directly from the order ID. See below for details.
  

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.