Request
This interface must be used to initiate a refund to payer after the money for the order has already been settled from Svea Payments to the merchant.
The process has several steps:
- Initiate a "refund after settlement" by using this interface.
- Do an actual money transfer from merchant's bank account to Svea Payments bank account by using the information given in the response of this interface. Merchant must use their own tools to do this money transfer. The amount and reference number of the money transfer must match the ones acquired by using this interface first.
- Svea Payments will refund the payer after receiving money from the merchant
Webstore delivers the request parameters in a <form> using POST method as hidden input fields (<input type=hidden>) 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 | REFUND_AFTER_SETTLEMENT | AN23 | C | Action being called (REFUND_AFTER_SETTLEMENT). |
| 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 | REFUND_AFTER_SETTLEMENT | AN40 | C | REFUND_AFTER_SETTLEMENT |
| Amount to be refunded | pmtc_cancelamount | e.g. 15,00 | N17 | C | Amount to be refunded. Decimal number with comma and two decimal digits, for example: 15,00 |
| Buyer's refund bank account | pmtc_payeribanrefund | IBAN number of the payer | AN36 | C | The IBAN is only required in case on bank payments. That is, card payments, invoice payments and part payments do not require it. If can be given though even if not required. |
| Cancel description | pmtc_canceldescription | AN500 | C | 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 * pmtc_payeribanrefund 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 refund | 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. |
info
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. 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
The response contains the following fields:
| Field | input name | value | Format | C/O | Description |
|---|---|---|---|---|---|
| Action code | pmtc_action | REFUND_AFTER_SETTLEMENT | AN6 | C | Action called (REFUND_AFTER_SETTLEMENT). |
| 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. | |
| Response code | pmtc_returncode | AN2 | C | Indicates success or failure. See below for the values and explanations of all the codes. | |
| Response text | pmtc_returntext | AN100 | C | Brief description of the failure reason. Empty in case of success. | |
| Hash | pmtc_hash | AN128 | C | 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. | |
| Reference | pmtc_pay_with_reference | a Finnish reference number | N20 | C | a Finnish reference number that should be used when paying money to Svea Payments after initiating this refund |
| Recipient name | pmtc_pay_with_recipientname | Svea Payments Oy | AN50 | C | Svea Payments Oy - The name to be used on the money transfer as the recipient. |
| Amount to refund | pmtc_pay_with_amount | i.e. 2,00 | N17 | C | The amount the merchant is willing to refund to payer, i.e. 2,00 |
| Maksuturva's IBAN | pmtc_pay_with_iban | The IBAN of the bank account to pay the money to. | AN36 | C | The IBAN of the bank account that the merchant should use to pay the money to. |
| Details of all the errors | errors | N/A | O | XML structure listing details of all the errors in the input message. |
Response code values
| Response code | Short description | Description |
|---|---|---|
| 00 | OK | Cancel received successfully |
| 20 | Not found | Payment not found |
| 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> |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<pmtc>
<pmtc_action>REFUND_AFTER_SETTLEMENT</pmtc_action>
<pmtc_version>0005</pmtc_version>
<pmtc_sellerid>6234567890ABCDE</pmtc_sellerid>
<pmtc_id>VXZ8KB43XDH617LAZYBU</pmtc_id>
<pmtc_returncode>00</pmtc_returncode>
<pmtc_returntext>Cancel received succesfully</pmtc_returntext>
<pmtc_hash>***</pmtc_hash>
<pmtc_pay_with_reference>00000666660000010007</pmtc_pay_with_reference>
<pmtc_pay_with_recipientname>Maksuturva Group Oy</pmtc_pay_with_recipientname>
<pmtc_pay_with_amount>2,00</pmtc_pay_with_amount>
<pmtc_pay_with_iban>FI7740123477777777</pmtc_pay_with_iban>
</pmtc>