Request (S2S HTTP POST)

In case the refund tools are supported for the given payment or order, the cancellations and refunds are allowed using this request as long as the payment has not reached the settlement phase (where it is about to be settled or has already been settled to merchant).

The merchant delivers the request parameters in a <form> using POST method as hidden input fields to address https://www.maksuturva.fi/PaymentCancel.pmt
(or https://test1.maksuturva.fi/PaymentCancel.pmt in test environment)

Skip to contents in this page

1 Request (S2S HTTP POST)
- 1.1 Optional change rows
  - 1.1.1 Pre-conditions for submitting change rows:
- 1.2 Change row types
2 Response (XML)
- 2.1 Response code values

Input name	Value	Format	Description

Input name	Value	Format	Description
COMPULSORY PARAMETERS: All of these must be present in the request.
`pmtc_action`	CANCEL	AN6	Action name. Always CANCEL.
`pmtc_version`	0005	AN4	Version of interface content or message
`pmtc_sellerid`		AN15	Technical seller id given to the webstore by Svea Payments.
`pmtc_id`		AN20	Unique Payment Identifier given to the payment transaction by the webstore.
`pmtc_amount`		AN17	Same value as in send in Create Payment API (`pmt_amount`). The amount must be presented with two decimals. The decimal delimiter is comma, e.g. 94,80
`pmtc_currency`		AN3	The payment currency. Same value as in send in Create Payment API (`pmt_currency`).
`pmtc_canceltype`	FULL_REFUND PARTIAL_REFUND PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES	AN40	Cancellation type that tells whether this is a full refund (FULL_REFUND) a reduction of price (PARTIAL_REFUND) a partial return of deliveries (PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES)
`pmtc_cancelamount`	e.g. 15,00	AN17	Amount to be refunded. The amount must be presented with two decimals without thousands separator. The decimal delimiter is a comma. For example: 15,00 Important! Used only in case of partial refunds! That is, this parameter should be omitted if cancellation type is full refund (FULL_REFUND).
`pmtc_resptype`	XML	AN4	Response type. Always XML.
`pmtc_keygeneration`	nnn e.g. 001	N3	Secret key generation or version related to the technical seller id. Default or initial value is 001.
OPTIONAL PARAMETERS: An optional parameter may be missing altogether, have an empty value or have a value of at least the minimum length.
`pmtc_cancel_id`		AN20	OPTIONAL, yet RECOMMENDED. Unique id for cancellation. It's recommended to use this field to give a unique idenfier for a refund. When given for one refund under the given order, there cannot be another refund for the same order with the same ID. This helps to prevent accidentally sending duplicate refunds.
`pmtc_payeribanrefund`	Finnish IBAN	AN36	OPTIONAL. Buyer's refund bank account number (Finnish IBAN). This is rarely needed. The IBAN might be required in case on bank payments. That is, card payments, mobile payments, invoice payments and part payments never require nor support it.
`pmtc_canceldescription`		AN500	OPTIONAL. Cancel description for the refund that can be shown to the buyer.
`pmtc_cancelreason`		AN5	OPTIONAL. Cancel reason code. Reason for the refund that can be shown to the buyer. Possible values are: NOTDE - Order has not been delivered WSIZE - Item has wrong size INCOR - Item does not correspond to order DEFEC - Item is broken or defective OUTOF - Item is out of stock OTHER - Other reason

Optional change rows

In addition to the data described above, it is possible to submit change order rows that describe in more detail the changes the merchant wishes to make to the order.

Pre-conditions for submitting change rows:

The merchant initiates the change. Change Rows can not be submitted, if the buyer has made a proposal for change via Buyer’s Assistant and the merchant is using the interface to accept/confirm payer's proposal.
The original order was submitted to Svea Payments with order rows.
The change is of type PARTIAL_REFUND or PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES. For a FULL_REFUND Svea Payments will do the order row level changes automatically.

NOTE! If any change rows are submitted, the total sum calculated from them must match the total amount of the change submitted in the field pmtc_cancelamount. If these do not match, but the difference is small, the Svea Payments system creates a rounding fix row to force the sum of change rows match the value of pmtc_cancelamount.

Change row types

Submitting the number of returned products of an original order row:

Changes (refunds) can be linked with original order rows by submitting a returned quantity of products in the parameter field pmtc_refund_quantity_of_original_rowN, where N is the original row number the change concerns. In this way, the change can be attributed to a particular quantity of a product that was part of the original order. The quantity returned cannot exceed the quantity in the original order. When pmtc_refund_quantity_of_original_rowN is submitted, then other parameters concerning that particular order row must not be submitted.

Submitting additional change rows:

In addition to or instead of the above (quantity to return), 0 to 300 additional change rows can be submitted. These can be used to alter the total amount of the change. Negative amount means returning/crediting money to the buyer. Positive amount means holding money by the merchant, for example due to handling or refund costs. Each additional change row requires 5-7 of the parameter fields of the table below to be submitted. Fields for article number and unit are optional. The price must be communicated either gross or the net, but not both.

Row type: Returned quantity of products (0-N pcs):

Resulting quantity based change row’s total amount (please notice the minus sign in front):
-round( pmtc_refund_quantity_of_original_row * pmt_row_price_gross * ( 1 - 0.01 * pmt_row_discountpercentage ) )

Input name	Value	Format	C/O	Description

Input name	Value	Format	C/O	Description
`pmtc_refund_quantity_of_original_rowN` (where N is the original order row number)	e.g.. 1	N8	C/O	The returned quantity of products of row N in the original order

Row type: Additional change row (0 to 300 pcs):

Additional change row’s total amount:
round( pmtc_additional_row_quantity * pmtc_additional_row_price_gross )

Input Name	Value	Format	C/O	Description

Input Name	Value	Format	C/O	Description
`pmtc_additional_row_nameN` (where N is number 1-300)	e.g. "Product 1"	AN40	C/O	Product or row name. In case of Invoice and B2B Invoice payment methods, these are shown in the invoice sent to the buyer. Max length: 40 characters
`pmtc_additional_row_descN`		AN1000	C/O	Row description. In case of Invoice and B2B Invoice payment methods, these are not shown in the invoice sent to the buyer.
`pmtc_additional_row_quantityN`	e.g. 1 or 1,00	AN8	C/O	Row quantity
`pmtc_additional_row_articlenrN`		AN10	O	Product article number
`pmtc_additional_row_unitN`	e.g. ”kpl”, "kg" or "pcs"	AN3	O	Row unit of quantity
`pmtc_additional_row_price_grossN`	e.g. -10,00	AN17	C	Row gross unit price (VAT included)
`pmtc_additional_row_vatN`	e.g. for VAT 25,5 %: 25,50	AN5	C/O	Row VAT percentage

Response (XML)

Input name	Value	Format	C/O	Description

Input name	Value	Format	C/O	Description
`pmtc_action`	CANCEL	AN6	C	Action called (CANCEL).
`pmtc_version`	0005	AN4	C	Version of interface content or message.
`pmtc_sellerid`		AN15	C	Technical seller id given to the webstore by Svea Payments.
`pmtc_id`		AN20	C	Unique Payment Identifier given to the payment transaction by the webstore.
`pmtc_returncode`	See table below	AN2	C	Response code. Indicates success or failure. See below for the values and explanations of all the codes.
`pmtc_returntext`		AN100	C	Brief description of the failure reason. Empty in case of success.
`errors`			O	Details of all the errors in the input message. An XML structure with root `errors` having multiple `error` elements below it. Each `error` element has attribute `type` with value `general` or `field`. In case of fields, there is also attribute `name` telling for example what input parameter the error is related to.

Response code values

Response code	Short description	Description

Response code	Short description	Description
`00`	OK	Cancel received successfully
`20`	Not found	Payment not found
`30`	Already settled	Payment already compensated and cannot be cancelled See Refund Payment After Settlement
`31`	Webstore and buyer cancellations mismatch	Cancel parameters from seller and payer do not match
`90`	Errors in input data	Errors in input data, specified in element `<errors>`
`91`	Duplicate detected	Payment cancellation failed, as this request was a duplicate based on the given unique identifier (`pmtc_cancel_id`)
`99`	Failed	Payment cancellation failed, reason specified in `<pmtc_returntext>`

Svea Payments API

Refund or Cancel Payment