Action code

pmt_action

NEW_PAYMENT_EXTENDED

AN50

4

C

NEW_PAYMENT_EXTENDED

Message version

pmt_version

0004

AN4

4

C

Version of interface content

Seller ID

pmt_sellerid

AN15

C

Technical user id given to the webstore by Svea Payments.

Unique Payment ID

pmt_id

AN20

C

Identifier given to the payment transaction by the webstore. Must be unique

Order id

pmt_orderid

AN50

C

Identifier given to the order by the webstore. Order id should be known by the buyer.

Payment reference number

pmt_reference

N20

4

C

Reference number given by the webstore and used when compensating the seller. The reference number must comply with the guidelines for a formal reference number issued by the Federation of Finnish Financial Services (FK, http://www.fkl.fi). The reference number must be at least 4 digits, the last of which is a check digit.

Payment due date

pmt_duedate

current date in format dd.MM.yyyy

AN10

10

C

A due date given to the payment by the webstore. Currently should be today.

Buyer's (user's) locale

pmt_userlocale

fi_FI, sv_FI, en_FI

AN5

5

O

Information on the country and language choices of the buyer. ll_CC, where ll is a two character ISO 639-1 language code and CC is a two character ISO 3166 alpha-2 country code. The default fi_FI will be used if the locale is null. For example sv_FI and en_FI will be accepted.

Sum of products and services of the order

pmt_amount

n,nn
e.g.. 50,00

AN17

4

C

The total gross sum of row types 1, 4, 5 and 6.
If the order does not contain any postal or handling cost rows (types 2 and 3), then this is the total amount of the order.
The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 94,80

Payment currency

pmt_currency

EUR

AN3

3

C

Currency used for the payment. Always EUR.

Ok return address (URL)

pmt_okreturn

AN200

C

The url to which the buyer's browser will be directed to in case of confirmed payments (the order has been paid)

Error return address (URL)

pmt_errorreturn

AN200

C

The error url to which the buyer's browser will be directed to if there is an error in the paying process. A querystring parameter Payment ID (pmt_id) is appended to this URL before redirection.

Cancel return address (URL)

pmt_cancelreturn

AN200

C

The cancel url to which the buyer's browser will be directed to if the buyer interrupts the paying process. A querystring parameter Payment ID (pmt_id) is appended to this URL before redirection.

Delayed payment return address (URL)

pmt_delayedpayreturn

AN200

C

The url to which the buyer's browser will be directed to if the user has confirmed using the credit transfer or giro payment method which means the payment has not yet been registered. A querystring parameter Payment ID (pmt_id) is appended to this URL before redirection.

Credit transfer or giro is not supported nowadays in "of-the-shelf" payment services. This is why we suggest using same address for both cancel and delayed payment return address (pmt_delayedpayreturn ~= pmt_cancelreturn).

Escrow in use

pmt_escrow

Satisfaction Guarantee payment service = Y
Direct payment service = N

A1

1

C

Tells whether escrow option is used with this payment. Values: Y/N
The value is always Y for Satisfaction Guarantee payment services (for example Maksuturva Gold).
Similarly, the value is always N for Direct payment services (for example eMaksut).

Escrow option changeable by buyer

pmt_escrowchangeallowed

N

A1

1

C

Currently always N.

Will webstore sends an invoice to the payer

pmt_invoicefromseller

Y/N

A1

1

O

Parameter can be used, if the chosen payment method is invoice or part payment.
Y = webstore will send an invoice to the payer
N (DEFAULT) = Maksuturva or the Credit Provider will send an invoice to the payer

Payment method pre-chosen in webstore

pmt_paymentmethod

FINN (esim. FI01)

AN4

4

O

OPTIONAL. Payment method’s code FInn.
Please check the possible values from chapter Response parameter descriptions.

Buyer’s social security number or company’s business identification code

pmt_buyeridentificationcode

AN11

9

O

Buyer’s social security number or company’s business identification code.

Buyer's name

pmt_buyername

AN100

C

Name of buyer (billing)

Buyer's billing address

pmt_buyeraddress

AN100

C

Address of buyer (billing). Street address or p.o. box

Buyer's postal code

pmt_buyerpostalcode

N20

C

Postal code of buyer (billing)

Buyer's city

pmt_buyercity

AN100

C

City of buyer (billing)

Buyer's country code

pmt_buyercountry

FI, SE, EN, ...

A2

C

Country code of buyer (billing)
(ISO 3166-1 alpha-2 standard based 2-character country code http://fi.wikipedia.org/wiki/ISO_3166)

Buyer's phone number

pmt_buyerphone

AN40

O

Phone number of buyer (billing)

Buyer's email address

pmt_buyeremail

AN320

O

Email address of buyer

Delivery recipient's name

pmt_deliveryname

AN100

C

Name of recipient (delivery). Street address or p.o. box (*

Delivery recipient's address

pmt_deliveryaddress

AN100

C

Address of recipient (delivery) (*

Delivery recipient's postal code

pmt_deliverypostalcode

N20

C

Postal code of recipient (delivery) (*

Delivery recipient's city

pmt_deliverycity

AN100

C

City of recipient (delivery) (*

Delivery recipient's country code

pmt_deliverycountry

FI, SE, EN, ...

A2

C

Country code of recipient (delivery) (*
(ISO 3166-1 alpha-2 standard based 2-character country code)

Sum of handling and delivery costs of the order

pmt_sellercosts

n,nn
e.g.. 10,00

AN17

4

C

The total gross sum of row types 2 and 3.
The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 7,40

Order row count (number of order rows)

pmt_rows

N4

1

C

The count or number of order rows as an integer.

Order row name

pmt_row_nameN

AN40

1

C

Name of this order row
Max length: 40 characters

Order row description

pmt_row_descN

AN1000

1

C

Detailed description of this order row

Order row quantity

pmt_row_quantityN

Preferably an integer value but also decimal number values with up to 2 decimal values are accepted. e.g. 1, 2 or 1,75

AN10

1

C

The quantity of this order row. Preferably an integer value but also decimal number values with up to 2 decimal values are accepted. e.g. 1, 2 or 1,75
For more details, see section Calculation Rules for Order Rows

Order row article or product number

pmt_row_articlenrN

AN100

1

O

Article or product number of this order row. Optional information.

Order row unit of quantity

pmt_row_unitN

e.g. kg, kpl

AN3

1

O

Unit of quantity of this order row, e.g. kg, l, m, kpl

Order row delivery date of package or service

pmt_row_deliverydateN

dd.mm.yyyy

AN10

10

C

Date in form dd.mm.yyyy – please set as current date, if there is no other logical value to use.

Order row gross unit price (VAT included)

pmt_row_price_grossN

n,nn
e.g.. 10,00

AN17

4

C/O

Gross unit price of product (VAT included).
Either net or gross value must be supplied, but not both!
The total gross price of one order row is:
row quantity * row gross unit price
For more details, see section Calculation Rules for Order Rows
The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 94,80

Order row net unit price (VAT excluded)

pmt_row_price_netN

n,nn
e.g.. 10,00

AN17

4

C/O

Net unit price of product (VAT excluded).
Either net or gross value must be supplied, but not both!
For more details, see section Calculation Rules for Order Rows
The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 94,80

Order row VAT percentage

pmt_row_vatN

n,nn
e.g.. 24,00

AN5

4

C

Decimal number with two decimal digits. The decimal delimiter is a comma. For example: 23,00 means ”23 %”
For more details, see section Calculation Rules for Order Rows

Order row Discount percentage

pmt_row_discountpercentageN

n,nn
e.g.. 10,00

AN5

4

C

Decimal number with two decimal digits. The decimal delimiter is a comma. For example: 10,00 means ”10 %”
For more details, see section Calculation Rules for Order Rows

Order row type

pmt_row_typeN

1 = product
2 = postal cost
3 = handling cost
4 = customized product (not eligible for returns)
5 = service
6 = discount

N5

1

C

1 = product
2 = postal cost
3 = handling cost
4 = customized product (not eligible for returns)
5 = service
6 = discount (always negative value)

Hash calculation character encoding.

pmt_charset

ISO-8859-1,
ISO-8859-15,
UTF-8

AN15

C

This field tells the character set that has been used to calculate the hash value for input data. Legal values are for now: ISO-8859-1, ISO-8859-15 and UTF-8.
Hash calculation is always done from binary data, which is not obvious in some programming languages. You must handle the transformation from character based data to binary data before hash calculation correctly. If it’s not possible to define the character set for hash calculation function, you must find out which character set is used internally by the hash algorithm.

Character encoding of input data (and of webstore)

pmt_charsethttp

ISO-8859-1,
ISO-8859-15,
UTF-8

AN15

This field tells the character encoding of the input data.
The Maksuturva payment interface handles HTTP request parameters according to this character encoding. Practically this is the character set reported by the
browser, when you’re browsing the checkout pages in the webstore.

Hash algorithm

pmt_hashversion

AN10

C

Name of the algorithm used to calculate the hash. For more detals, see section Hash Generation

Hash

pmt_hash

AN128

32

C

Hash calculated from the request fields listed below and webstore’s secret key:

• pmt_action

• pmt_version

• pmt_id

• pmt_orderid

• pmt_reference

• pmt_duedate

• pmt_amount

• pmt_currency

• pmt_okreturn

• pmt_errorreturn

• pmt_cancelreturn

• pmt_delayedpayreturn

• pmt_escrow

• pmt_escrowchangeallowed

• pmt_invoicefromseller (only if present in request)

• pmt_paymentmethod (only if present in request)

• pmt_buyeridentificationcode (only if present in request)

• pmt_buyername

• pmt_buyeraddress

• pmt_buyerpostalcode

• pmt_buyercity

• pmt_buyercountry

• pmt_deliveryname

• pmt_deliveryaddress

• pmt_deliverypostalcode

• pmt_deliverycity

• pmt_deliverycountry

• pmt_sellercosts

• pmt_marketplacecommission (only if present in request)

• pmt_marketplacereference (only if present in request)

• for each order row, one row at a time:

  • pmt_row_nameN

  • pmt_row_descN

  • pmt_row_quantityN

  • pmt_row_articlenrN

  • pmt_row_unitN

  • pmt_row_deliverydateN

  • pmt_row_price_grossN

  • pmt_row_price_netN

  • pmt_row_vatN

  • pmt_row_discountpercentageN

  • pmt_row_typeN

  • <webstore's secret key>

For further information, see Hash Generation.

Secret key generation

pmt_keygeneration

N3

C

Webstore's secret key generation or version. Default or initial value is 001.

Optional rows

Marketplace commission amount
(not in use in most cases)

pmt_marketplacecommission

n,nn
e.g. 10,00

AN17

4

O

The commission amount reserved for marketplace.
Please contact Svea Payments support if you intend to use this parameter!

Marketplace commission reference number
(not in use in most cases)

pmt_marketplacereference

N20

4

O

The reference number used when commission is settled to marketplace.
Please contact Svea Payments support if you intend to use this parameter!