Versions Compared

Old Version 1

changes.mady.by.user Aleksi Ahonen

Saved on

compared with

New Version 2

changes.mady.by.user Aleksi Ahonen

Saved on

Key

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

Request

Cancellations and refunds are allowed as long as the order is not being settled or has not been settled to webstore.

Webstore 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)

Table of Contents

Field

Input name

Value

Format

C/O

Description

Action code

pmtc_action

CANCEL

AN6

C

Action being called (CANCEL).

Message version

pmtc_version

0005

AN4

C

Version of the interface content.

Seller ID

pmtc_sellerid

AN15

C

Seller ID given to the webstore by Svea Payments. Technical interface user id.

Payment ID

pmtc_id

AN20

C

Unique identifying number given to the payment transaction by webstore.

Payment amount

pmtc_amount

AN17

C

The original amount of the order. Same value as in send in Payment API (pmt_amount). The amount must be presented with two decimals. The decimal delimiter is comma, e.g. 94,80

Payment currency

pmtc_currency

AN3

C

The payment currency. Same value as in send in Payment API (pmt_currency).

Cancellation type

pmtc_canceltype

FULL_REFUND
PARTIAL_REFUND
PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES

AN40

C

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)

Amount to be refunded

pmtc_cancelamount

e.g. 15,00

AN17

C/O

Amount to be refunded. Decimal number with comma and two decimal digits, for example: 15,00

Important! Used only in case of partial refunds! That is, this parameter should be ommited if cancellation type is full refund (FULL_REFUND).

Buyer's refund bank account

pmtc_payeribanrefund

IBAN number
Important! Available only if separately agreed on with Svea Payments.

AN36

O

This is only applicable if webstore has separately acquired tools from Maksuturva which allow webstore to make refunds independently. That is, Maksuturva does not contact buyer. Furthermore, buyer has no Web Buyer's Services at his or her use. In these cases it might be neccessary for the webstore to pass a IBAN for the refund. The IBAN is only required in case on bank payments. That is, card payments, invoice payments and part payments do not require it.

Important! Avaiiable only if separately agreed on with Svea Payments.

Cancel description

pmtc_canceldescription

AN500

O

Optional description for the refund that could be should to the buyer.

Cancel reason code

pmtc_cancelreason

AN5

O

Optional reason for the refund that could be should to the buyer. Possible values are:

Code / Description

  • 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

Response type

pmtc_resptype

XML

AN4

C

Always XML

Hash algorithm

pmtc_hashversion

AN10

C

Name of the algorithm used to calculate the hash. For more details, see section Hash Calculation.

Hash

pmtc_hash

AN128

C

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

  • pmtc_action

  • pmtc_version

  • pmtc_sellerid

  • pmtc_id

  • pmtc_amount

  • pmtc_currency

  • pmtc_canceltype

  • pmtc_cancelamount (if pmtc_canceltype is either PARTIAL_REFUND or PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES)

  • pmtc_payeribanrefund (if given)

For more details, see section Hash Calculation.

Secret key generation

pmtc_keygeneration

Default: 001

N3

C

Generation number of the secret key given to the seller by Svea Payments.
Default is 001

Unique id for cancellation

pmtc_cancel_id

AN20

O

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.

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 Web Buyer's Services 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 the above, 0-3 additional change rows can be submitted. They 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, 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):

Field

Input name

Value

Format

C/O

The returned quantity of products of row N in the original order

pmtc_refund_quantity_of_original_rowN
(where N is the original order row number)

e.g.. 1

N8

C/O

Row type: Additional change row (0-3 pcs):

Field

Input Name

Value

Format

C/O

Product or row name

pmtc_additional_row_nameN
(where N is number 1-3)

e.g. "Product 1"

AN40

C/O

Row descrption

pmtc_additional_row_descN

AN1000

C/O

Row quantity

pmtc_additional_row_quantityN

e.g.. 1 or 1,00

AN8

C/O

Product article number

pmtc_additional_row_articlenrN

AN10

Row unit of quantity

pmtc_additional_row_unitN

e.g. "kg" or "pcs"

AN3

Row gross unit price (VAT included)

pmtc_additional_row_price_grossN
(either gross or net must be submitted, but not both!)

e.g. 10,00

AN17

C/O

Row net unit price (VAT excluded)

pmtc_additional_row_price_netN
(either gross or net must be submitted, but not both!)

e.g. 8,00

AN17

C/O

Row VAT percentage

pmtc_additional_row_vatN

e.g. for VAT 24 %: 24,00

AN5

C/O

Not that ANxx means that the field contains a maximum of xx alphanumeric characters. N means numeric. C means that the field is compulsory and O means it is optional. C/O means that the field is conditionally compulsory (for example two alternative fields pmt_row_price_grossN and pmt_row_price_netN of which one, and only one, must be present). An optional field may be missing altogether, have an empty value or have a value of at least the minimum length. That is, minimum length does not make a field mandatory but when it is present in the request it must have at least the minimum length.

Response

Field

Input name

Value

Format

C/O

Description

Action code

pmtc_action

CANCEL

AN6

P

Action called (CANCEL).

Message version

pmtc_version

0005

AN4

P

Version of the interface content.

Seller ID

pmtc_sellerid

AN15

P

Seller ID given to the webstore by Svea Payments. Technical interface user id.

Payment ID

pmtc_id

AN20

P

Unique identifying number given to the payment transaction by webstore.

Response code

pmtc_returncode

AN2

P

Indicates success or failure. See below for the values and explanations of all the codes.

Response text

pmtc_returntext

AN100

P


Brief description of the failure reason. Empty in case of success.

Hash

pmtc_hash

AN128

P

Hash calculated from predefined message fields and the webstore's secret key. Uses the same version, key generation etc values that were in the request. The following fields are used to calculate the hash:

  • pmtc_action

  • pmtc_version

  • pmtc_sellerid

  • pmtc_id

  • pmtc_returntext

  • pmtc_returncode

For more details, see section Hash Calculation.

Details of all the errors

errors

N/A

V

XML structure listing details of all the errors in the input message.

Response code values

Response code

Short description

Description

00

OK

Cancel received succesfully

20

Not found

Payment not found

30

Already settled

Payment already compensated and cannot be cancelled

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>