Refund Payment After Settlement

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 identifier 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.

Response

The response contains the following fields:

Field

Input Name

Value

Format

C/O

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>

Example Response

<?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>