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.
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 "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).
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.
Please notice that
pmt_escrow parameter value is determined by the payment service type webstore uses (wrong value results into a technical error):
Satisfaction Guarantee payment service:
Direct payment service:
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 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 buyer chooses payment method on a page displayed by Svea Payments, he/she agrees on the terms and conditions of Satisfaction Guarantee payments. On the other hand, if buyer chooses payment method in the webstore that is using Satisfaction Guarantee, webstore must display the aforementioned terms and conditions in the webstore and ensure the buyer agrees on 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 (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_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 (
pmt_row_price_net). In such case the Maksuturva 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 (
pmt_row_price_gross). In such case the Maksuturva system will calculate net price, if necessary. Calculating the net price may be needed when Maksuturva 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 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_sellercosts rounding error).
pmt_row_price_gross = product unit price including VAT, without considering discount
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.
Gross and net prices have the following relationship:
IF net price was supplied:
Row sum after reducing the discount, without VAT:
IF gross price was supplied:
Row sum after reducing the discount, without VAT:
Row sum of VAT:
(VAT is calculated based on the reduced net price):
Row total amount:
(payable in effect on the gross amount)
The gross price of the whole order:
In the interfaces all the money amounts and percentages must be presented with two decimals using comma as the decimal delimiter.