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)
| 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 | N17 | 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 | N17 | 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 | Desctiption |
|---|---|---|---|---|---|
| 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> |