Versions Compared

Version Old Version 6 New Version Current
Changes made by

Aleksi Ahonen

Aleksi Ahonen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Webstore uses this service to deliver order information or payment transaction information to Svea Payments. Payer chooses a payment method and pays the order or decides to interrupt the payment process.

Return addresses

The payment process outcome is usually indicated by the webstore address (URL) to which the buyer is redirected.

  • OK return address (pmt_okreturn): Payment confirmed successfully

  • Cancel return address (pmt_cancelreturn): Payment process interrupted (buyer probably decided to interrupt it)

  • Error return address (pmt_errorreturn): Payment process interrupted because of an error.

  • Delayed payment return address (pmt_delayedpayreturn): Buyer confirmed that he or she will pay the order later by credit transfer or giro (payment not yet actually confirmed).

    • Important! Credit Transfer or Giro is not supported nowadays in "ofoff-the-shelf" payment services. This is why we suggest using same address for both cancel and delayed payment return address(pmt_delayedpayreturn ~= pmt_cancelreturn).

In some cases, the buyer never manages in returning to the webstore. This is why it is crucial that every webstore also integrates and uses Payment Status Query API. See the interface description for full details and argumentation.

Escrow parameter

Please notice that pmt_escrow return parameter value is determined by the payment service type webstore uses (wrong value results into a technical error):
Satisfaction Guarantee and may be different from the value webstore sends as a parameter for new payment:
Buyer’s Assistant payment service: pmt_escrow=Y
Direct payment service: pmt_escrow=N

Choosing the payment method already in webstore

When Svea Payments and Webstore has mutually agreed on it, webstore can display the available payment methods for he the buyer in their webstore. In this scenario, the Svea Payments page for choosing the payment method is skipped altogether. This requires the webstore to retrieve the available payment methods per order using Retrieve Available Payment Methods API. Also, the Payment API must contain the code of the payment method (pmt_paymentmethod) buyer chose in the webstore. When the buyer chooses payment method on a page displayed by Svea Payments, he/she agrees on the terms and conditions of Satisfaction Guarantee paymentsthe. Buyer’s Assistant service, if the webstore is using it. On the other hand, if the buyer chooses payment method in the webstore that is using Satisfaction Guaranteethe Buyer’s Assistant, the webstore must display the aforementioned terms and conditions in the webstore and ensure the buyer agrees on to them.

When Svea Payments page for choosing the payment method is skipped the buyer's email address is a compulsory parameter in the Payment Request. Absence of the email address causes an error and the buyer is returned to the web store.

Delivery address of the order

The delivery address (pmt_deliveryaddress etc.) of each order must represent the real address to which the order is actually delivered. For example if buyer gives his home address the billing address (pmt_buyeraddress etc.) but chooses a delivery to a Parcel Point or chooses to fetch the product from the store, the delivery address must be either the Parcel Point's or store's address.

Order Rows

Order rows (fields beginning with "pmt_row") have been mandatory since new payment interface version 0004 was represented in 2011. Order rows should contain comprehensive information about the order. Also, the amount fields (pmt_amount and pmt_sellercosts) must match the calculated gross sum of the associated row types.

Each order row can contain either net or gross unit price, but never both; that is not allowed.

Using net unit prices

If the webstore uses net price as basis for its calculations, it’s recommended to include that net price in the message sent to Maksuturva Svea Payments (pmt_row_price_net). In such case the Maksuturva Svea Payments system will calculate the prices in the same way as the webstore – gross is calculated from net price and VAT values.

pmt_row_price_net = product unit price excluding VAT, without considering discount

Using gross unit prices

If the webstore uses gross price as basis for its calculations, it’s recommended to include that gross price in the message sent to Maksuturva Svea Payments (pmt_row_price_gross). In such case the Maksuturva Svea Payments system will calculate net price, if necessary. Calculating the net price may be needed when Maksuturva Svea Payments forwards the order specification data to some payment or credit provider, that requires the data as net amounts. Calculating net from gross and then again gross from net may introduce rounding problems. These are entirely handled by Maksuturva Svea Payments system by adding up to two extra order rows to the order, that fix the rounding errors (one extra row possibly needed for both pmt_amount and pmt_sellercosts rounding error).

pmt_row_price_gross = product unit price including VAT, without considering discount

Handling discounts

A discount can be sent as a percentage value per order row, or there can be separate discount rows with negative price. It’s recommended to specify discount as a percentage inside each order row. This, for example, makes it easier to handle certain refund cases; discounts need not be handled separately when they are included in product rows.

Calculation Rules for Order Rows

Calculation rules concerning the order specification data are described below. Variables beginning with "pmt" represent field data sent to the new payment interface. Variables beginning with "Calc" are calculated values used to check the validity of interface field data.

Skip to contents in this page

Table of Contents

Gross and net prices have the following relationship:

Code Block
languagejava
pmt_row_price_gross = round ( pmt_row_price_net * ( 1 + 0.01 * pmt_row_vat ) )

IF net price was supplied:

(pmt_row_price_net)

Row sum after reducing the discount, without VAT:

Code Block
languagejava
CalcRowAmountExVAT = round (
                         round ( pmt_row_quantity * pmt_row_price_net ) *
                          ( 1 - 0.01 * pmt_row_discountpercentage )
                     )

IF gross price was supplied:

(pmt_row_price_gross)

Row sum after reducing the discount, without VAT:

Code Block
languagejava
CalcRowUnitNetPrice = round (
                          pmt_row_price_gross / ( 1 + 0.01 * pmt_row_vat )
                      )
CalcRowAmountExVAT = round (
                         round ( pmt_row_quantity * CalcRowUnitNetPrice ) *
                          ( 1 - 0.01 * pmt_row_discountpercentage )
                     )

Row sum of VAT:

(VAT is calculated based on the reduced net price):

Code Block
languagejava
CalcRowVAT = round (CalcRowAmountExVAT * ( 0.01 * pmt_row_vat ))

Row total amount:

(payable in effect on the gross amount)

Code Block
languagejava
CalcTotalRowAmount = round ( CalcRowAmountExVAT + CalcRowVAT )

The gross price of the whole order:

Code Block
languagejava
== pmt_amount + pmt_sellercosts
== sum ( CalcTotalRowAmount )

pmt_amount:

Code Block
languagejava
== total sum of CalcTotalRowAmount for product and service rows (types 1, 4, 5 and 6)

pmt_sellercosts:

Code Block
languagejava
== total sum of postal and handling cost rows (types 2 and 3)

Payment ID

pmt_id

AN20

C

Unique Identifying number given to the transaction by the webstore. Same as in the input message

In the interfaces all the money amounts and percentages must be presented with two decimals using comma as the decimal delimiter.

New Payment Response

The response data sent webstore by redirecting buyer's browser to the ok return address in cases where buyer has successfully confirmed the payment. Webstore may deliver the order immediately if wanted.

If the buyer interrupts the payment process, the buyer's browser will be redirected to the cancel return address.

If there was an error in the process, the buyer's browser will be redirected to the error return address.

These return scenarios have been briefly described already in section Payment.

NOTE: For interrupted/cancelled or erroneus payments, only querystring parameter pmt_id is appended to the response URL, and no other parameters.

Usually the pmt_sellercosts value in the response is exactly the same as the in the original new payment request. However, some payment methods make it possibly for the webstore to determine an additional invoicing fee or extra handling cost (a fixed money amount). In cases where the buyer chooses such payment method, the invoicing fee is added as a new order row to the order by Maksuturva. Also the pmt_sellercosts value is increased by the same fee amount. In these cases the response contains a pmt_sellercosts value that is greater than the original value in the request. The difference could be exactly the invoicing fee and nothing else.

Response validation

Fields that are generated by Svea Payments and submitted as part of the response, should be formally validated, as defined in the interface specification.

Hash must be calculated from the data in response and that hash must be compared with the pmt_hash field of the response. Calculated value may not differ from the one in response. The hash algorithm used for the response hash is THE SAME as was used for the corresponding payment request.

If the checks above are successful, the response can be handled as a valid one.

Field

Input name

Value

Format

C/O

Description

Action code

pmt_action

NEW_PAYMENT_EXTENDED

AN50

C

NEW_PAYMENT_EXTENDED

Message version

pmt_version

0004

AN4

C

Version of interface content. Same as in the input message.

.

Reference number

pmt_reference

N20

C

Reference number given by the webstore and used when the order is settled to the seller. The reference number is in its technical format, i.e. with leading zeros, without spaces and with total length of 20 digits. The response hash is calculated with the reference number in this format. Same as in the input message.

Sum of products and services of the order

pmt_amount

AN17

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 is presented with two decimals. The decimal delimiter is a comma, e.g. 94,80

Payment currency

pmt_currency

EUR

AN3

C

Currency of the payment. Always EUR.

Sum of handling and delivery costs of the order

pmt_sellercosts

N17

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

Payment method

pmt_paymentmethod

AN4

C

Indicates what payment method the buyer chose. For available codes, see section Payment Method Codes.

Important! Please do not use the values of the table above in production. Instead, retrieve official payment method codes and names using GetPaymentMethods.pmt API (see chapter Retrieve Available Payment Methods).

Escrow is being used

pmt_escrow

Y/N

AN1

C

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

Hash

pmt_hash

AN128

C

Hash calculated from predefined message fields and the webstore's secret key. The following fields are used to calculate the hash:

  • pmt_action

  • pmt_version

  • pmt_id

  • pmt_reference

  • pmt_amount

  • pmt_currency

  • pmt_sellercosts

  • pmt_paymentmethod

  • pmt_escrow

For more details, see section Hash Calculation.

Payment Method Codes

Code

Description (in Finnish)

FI01

Nordea E-maksu

FI02

Danske Bank Verkkomaksu

FI03

Aktia verkkomaksu

FI04

POP Pankin verkkomaksu

FI05

Tapiola Pankki Verkkomaksu

FI06

Osuuspankki Verkkomaksu

FI07

Ålandsbanken E-maksu

FI08

Säästöpankin verkkomaksu

FI09

Handelsbanken Verkkomaksu

FI10

S-pankki Verkkomaksu

FI11

Oma Säästöpankin verkkomaksu

FI50

Korttimaksu (Visa, Visa Electron, MasterCard)

FI51

Korttimaksu

FI52

American Express

FI53

Diners Club

FI54

MobilePay

FI55

Masterpass

FI60

Maksuturva Lasku

FI61

Maksuturva Erämaksu

FI70

SveaWebPay Lasku

FI71

SveaWebPay Osamaksu

FI72

Yrityslasku

USPP

PayPal

RBIP

Resurs Bank Lasku/Erämaksu

RBIN

Resurs Bank Lasku

RBPP

Resurs Bank Osamaksu

RBCD

Resurs Bank Kortti / Tili

RBRC

Resurs Bank Uusi kortti / tili

PLDP

Dotpay

EEMK

Maksekeskus

PIVO

Pivo

PVCD

Pivo (korttimaksu) - Important! Do not use when creating a new payment!

PVCT

Pivo (tilisiirto) - Important! Do not use when creating a new payment!

SIIR

Siirto