maksunappi

A Node.js library for online payments in Finland. Includes test configurations for Nordea, DanskeBank, Handelsbanken, OP, Aktia, Ålandsbanken, S-Pankki, Säästöpankki and POP Pankki.

Currently requires Express.

About

From Reaktor with love.

Apply for juicy positions at reaktor.com/careers and prepare for The Culling.

Install

npm install maksunappi

Testing

Run tests with grunt.

Usage and configuration

Basic usage (using default configurations)

var generalOptions = {
  appHandler: app, // an Express application
  hostUrl: 'http://domain.here.com:port', // required for return URLs
  logger : logger //optional winston logger instance
};
 
var maksunappi = require('maksunappi').create(generalOptions);

Bank configuration

Changing configurations (code example)

var bankOptions = [
  {
    id : 'nordea',
    imgPath : '/path/to/my/image.png',
    vendorId : 'production id',
    checksumKey : 'production key'
  },
  {
    id : 'op',
    name: 'Osuuspankki',
    algorithmType: 'sha256'
  }
];
 
var maksunappi = require('maksunappi').create(generalOptions, bankOptions);

The following options can only be configured in this initial configuration phase (see "Bank configuration options" below for other options that can be configured either here on on a per-request basis):

• id - identifier for the bank (this identifies the bank you are about to configure, see below for options)
• paymentUrl - url for the online payments service
• imgPath - path for the image used for the HTML form (or "button")
• checksumKey - vendor specific key used in computing the MAC

Possible values for id are:

Bank	ID
Aktia	aktia
Danskebank	danskebank
Handelsbanken	handelsbanken
Nordea	nordea
Osuuspankki	op
POP Pankki	poppankki
S-Pankki	spankki
Säästöpankki	saastopankki
Ålandsbanken	alandsbanken

Configuration options with an unrecognized id are ignored.

Bank configuration options

The following table describes the different options you can use to configure banks. These options are then mapped to bank specific form fields. E.g paymentVersion is mapped to 'NET_VERSION' in Aktia's case and to 'VERSIO' in DanskeBank's.

Any of these options may be either set as general options for a bank in the initial configuration or overridden in button options on a per-request basis.

The library performs minimal checks on inputs. Required fields are checked but reference numbers and input lengths are generally not. Depending on the field and bank, not observing the length limits specified in bank specific interface specification documents may or may not have an effect on the success of the request. Failure to provide an input for a required field results in an exception.

M = mandatory, O = optional, - = not in use

Field	Aktia	Ålandsbanken	Danskebank	Handelsbanken	Nordea	Osuuspankki	POP Pankki	S-Pankki	Säästöpankki
paymentVersion	M	M	M	M	M	M	M	M	M
requestId	M	M	-	M	M	M	M	M	M
vendorId	M	M	M	M	M	M	M	M	M
vendorAccount	-	M	-	-	O	-	-	M	-
vendorName	-	M	-	-	O	-	-	M	-
language	-	M	O	-	O	-	-	M	-
amount	M	M	M	M	M	M	M	M	M
currency	M	M	M	M	M	M	M	M	M
reference	M	M	M	M	O	M	M	M	M
dueDate	M	M	M	M	M	O	M	M	M
messageForBankStatement	-	-	-	-	O	O	-	-	-
confirm	M	M	-	M	O	O	M	M	M
keyVersion	-	M	-	-	M	M	-	M	-
cookie	-	M	-	-	-	-	-	-	-
algorithmType	-	-	M	-	-	-	-	-	-
mobile	-	-	-	-	O	-	-	-	-
messageForWebForm	O	O	-	O	-	O	O	O	O

Notice that Aktia and Handelsbanken share the same mandatory and optional fields.

Do remember to configure vendorName and vendorAccount for all banks which require them when not using the test credentials (vendorId, checksumKey)!

Input formatting

Option values should be in the following formats:

Field	Format	Example	Notes
paymentVersion	(convertible to) integer	3 / "3" / "003"	Is automatically formatted to comply with bank specifications.
requestId	string of numbers	"201401301400391"	Integer values are fine too (watch out for floating point precision problems).
vendorId	string	"TAPESHOPID" / "12345678"
vendorAccount	string	"448710-126"
vendorName	string	"TESTIKAUPPA"
language	ISO 693-1 (string)	"FI" / "SV" / "EN"	Note that some banks only support a subset of these languages ("FI"/"SV").
amount	floating point / integer	25 / 50.5
currency	string	"EUR"
reference	string	"2014013014003919"	See "Generating reference numbers" below.
dueDate	string / JavaScript Date	"EXPRESS" / new Date()	See "Additional notes" below
messageForBankStatement	string		Is automatically split into rows according to bank specifications. The message may be clipped if too long. Message is shown in the bank statement
confirm	boolean	true / false
keyVersion	(convertible to) integer		Similar to paymentVersion.
cookie	boolean
algorithmType	string	'md5' / 'sha256'	'md5' is the default for most banks.
mobile	boolean
messageForWebForm	string		message is only shown to the buyer in the webform

Additional notes concerning due dates:

Always use either "EXPRESS" or a JavaScript Date object, not e.g. date strings. "EXPRESS" works with all banks (for DanskeBank, the library converts it into a date). Dates in the past are automatically converted into today's date.

Note that some banks (namely Ålandsbanken and S-Pankki) only allow EXPRESS payments.

Mapping to form fields

The following table describes the mapping from options to bank specific form fields, if you need to refer to the original specifications for help with parameters.

Field	Aktia	Ålandsbanken	Danskebank	Handelsbanken	Nordea	Osuuspankki	POP Pankki	S-Pankki	Säästöpankki
paymentVersion	NET_VERSION	AAB_VERSION	VERSIO	NET_VERSION	SOLOPMT_VERSION	VERSIO	NET_VERSION	AAB_VERSION	NET_VERSION
requestId	NET_STAMP	AAB_STAMP	-	NET_STAMP	SOLOPMT_STAMP	MAKSUTUNNUS	NET_STAMP	AAB_STAMP	NET_STAMP
vendorId	NET_SELLER_ID	AAB_RCV_ID	KNRO	NET_SELLER_ID	SOLOPMT_RCV_ID	MYYJA	NET_SELLER_ID	AAB_RCV_ID	NET_SELLER_ID
vendorAccount	-	AAB_RCV_ACCOUNT	-	-	SOLOPMT_RCV_ACCOUNT	-	-	AAB_RCV_ACCOUNT	-
vendorName	-	AAB_RCV_NAME	-	-	SOLOPMT_RCV_NAME	-	-	AAB_RCV_NAME	-
language	-	AAB_LANGUAGE	lng	-	SOLOPMT_LANGUAGE	-	-	AAB_LANGUAGE	-
amount	NET_AMOUNT	AAB_AMOUNT	SUMMA	NET_AMOUNT	SOLOPMT_AMOUNT	SUMMA	NET_AMOUNT	AAB_AMOUNT	NET_AMOUNT
currency	NET_CUR	AAB_CUR	VALUUTTA	NET_CUR	SOLOPMT_CUR	VALUUTTALAJI	NET_CUR	AAB_CUR	NET_CUR
reference	NET_REF	AAB_REF	VIITE	NET_REF	SOLOPMT_REF	VIITE	NET_REF	AAB_REF	NET_REF
dueDate	NET_DATE	AAB_DATE	ERAPAIVA	NET_DATE	SOLOPMT_DATE	ERAPVM	NET_DATE	AAB_DATE	NET_DATE
messageForBankStatement	-	-	-	-	SOLOPMT_MSG	VIEST1 / VIEST2	-	-	-
confirm	NET_CONFIRM	AAB_CONFIRM	-	NET_CONFIRM	SOLOPMT_CONFIRM	VAHVISTUS	NET_CONFIRM	AAB_CONFIRM	NET_CONFIRM
keyVersion	-	AAB_KEYVERS	-	-	SOLOPMT_KEYVERS	TARKISTE-VERSIO	-	AAB_KEYVERS	-
cookie	-	BC_UseBVCookie	-	-	-	-	-	-	-
algorithmType	-	-	ALG	-	-	-	-	-	-
mobile	-	-	-	-	SOLOPMT_PMTTYPE	-	-	-	-
messageForWebForm	NET_MSG	AAB_MSG	-	NET_MSG	-	VIESTI	NET_MSG	AAB_MSG	NET_MSG

Create payment HTML forms for configured banks

var requestId = "123456789876543";
var referenceNum = <generate reference here>; // see "Generating reference numbers" below
var options = {
                requestId: requestId,
                amount: 25,
                messageForBankStatement: "Lorem ipsum dolor sit amet...",
                reference: referenceNum,
                language: 'FI'
              };
 
var buttonHtml = maksunappi.paymentButton('nordea', options);

...or if you just want the request parameters without generating any HTML:

var params = maksunappi.buildRequestParams('nordea', options);

Generating reference numbers / check numbers

Finnish reference number:

var numericIdentifier = '1234556789'; // e.g. a timestamp + an id
var referenceNumber = maksunappi.referenceNumbers.toFinnishPaymentReference(numericIdentifier);

International RF reference number (might not be supported by all banks):

var referenceNumber = maksunappi.referenceNumbers.toRFReference(finnishReferenceNumber);

Usually if the bank requires both a requestId and a reference, you should use the requestId as the basis (numericIdentifier) for the reference number.

Get a listing of all configured banks (IDs)

var banks = maksunappi.banks
// => ['danskebank', 'handelsbanken', 'nordea',
//     'op', 'aktia', 'alandsbanken', 'spankki']

Response handling

The module binds paths /epayments/ok/<bank id> (GET and POST, for all bank ids), /epayments/cancel (only GET) and /epayments/reject (only GET) to the given Express app for use as return urls.

Response handling is event based.

maksunappi.on('success', function (request, response, data) {
  // Payment was successful and the customer returned to the site.
  // Normalized query data can be accessed in the data parameter.
  // Note: for many banks, the query string is empty unless the "confirm"
  // parameter is set to true.
});
 
maksunappi.on('mac-check-failed', function (request, response, data) {
  // Same as above but MAC check failed, so the data was faulty.
});
 
maksunappi.on('cancel', function (request, response) {
  // User cancelled the payment.
});
 
maksunappi.on('reject', function (request, response) {
  // The payment was rejected by the bank.
});

Normalized response data

The normalized query string data contains the following fields:

X = present, - = not present

Field	Aktia	Ålandsbanken	Danskebank	Handelsbanken	Nordea	Osuuspankki	POP Pankki	S-Pankki	Säästöpankki
version	X	X	X	X	X	X	X	X	X
requestId	X	X	-	X	X	X	X	X	X
reference	X	X	X	X	X	X	X	X	X
archivedId	X	X	-	X	X	X	X	X	X
mac	X	X	X	X	X	X	X	X	X
algorithm	X	-	-	X	-	-	X	-	X
macVersion	-	-	-	-	-	X	-	-	-
currency	-	-	X	-	-	-	-	-	-
vendorId	-	-	X	-	-	-	-	-	-
dueDate	-	-	X	-	-	-	-	-	-
paymentStatus	-	-	X	-	-	-	-	-	-
paymentSum	-	-	X	-	-	-	-	-	-
paymentMethod	-	-	X	-	-	-	-	-	-

Version numbers (version, macVersion) are converted to integers in the normalized data.

Sample application

See sample/app.js for a simple usage example. Run the sample app locally with node sample/start-sample.js.