Request parameters
Payment status query is possible as soon as the payment has been successfully received and saved by Svea Payments.
Webstore delivers the query parameters in a <form>
using POST method as hidden input fields (<input type=hidden>
) to address https://www.maksuturva.fi/PaymentStatusQuery.pmt
(or https://test1.maksuturva.fi/PaymentStatusQuery.pmt
in testing environment).
Field | input name | Description | value | Format | C/O |
---|---|---|---|---|---|
Action code | pmtq_action | PAYMENT_STATUS_QUERY | PAYMENT_STATUS_QUERY | AN50 | C |
Message version | pmtq_version | Version of the interface content. | 0005 | AN4 | C |
Seller ID | pmtq_sellerid | Seller ID given to the webstore by Svea Payments. Technical interface user id. | AN15 | C | |
Payment ID | pmtq_id | Unique identifying number given to the payment transaction by webstore. | AN20 | C | |
Response type | pmtq_resptype | Currently only XML is supported. | XML | AN4 | C |
Hash algorithm | pmtq_hashversion | Name of the algorithm used to calculate the hash. For more details, see section Hash Calculation. | AN10 | C | |
Hash | pmtq_hash | Hash calculated from predefined message fields and the webstore's secret key. The following fields are used to calculate the hash: pmtq_action pmtq_version pmtq_sellerid pmtq_id For more details, see section Hash Calculation. | AN128 | C | |
Secret key generation | pmtq_keygeneration | Generation number of the secret key given to the seller by Svea Payments. Default is 001 | N3 | C |
Response parameter
The character encoding of response message (XML) is UTF-8. Additionally, the only supported response type is XML. These restrictions are present because buyer’s address information received from credit check (for invoice and part payment) can contain characters that are not present in character sets ISO-8859-1 or ISO-8859-15.
Field | input name | Description | value | Format | C/O |
---|---|---|---|---|---|
Action code | pmtq_action | PAYMENT_STATUS_QUERY | AN50 | C | |
Message version | pmtq_version | Version of interface content. Same as in the input message. | AN4 | C | |
Seller ID | pmtq_sellerid | Seller ID given to the webstore by Svea Payments. Technical interface user id. | AN15 | C | |
Payment ID | pmtq_id | Unique identifying number given to the payment transaction by webstore. | AN20 | C | |
Sum of products and services of the order | pmtq_amount | The total sum of products and services of the order. If the order does not contain any postal or handling costs, then this is the total amount of the order. The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 94,80 | AN17 | C | |
Response code | pmtq_returncode | Indicates success or failure. Values and explanations of all the codes can be found at section Response code values. | AN | C | |
Response text | pmtq_returntext | Brief description of the response code. | AN100 | C | |
Tracking codes of the deliverables of the order | pmtq_trackingcodes | Tracking codes or information of untraceable deliveries submitted to Maksuturva system regarding this payment. Format [XX|XY|YY] 0-n times depending on the count of submitted tracking codes or information of untraceable deliveries. XX = Delivery type code XY = Tracking code, or the submitted text in case of untraceable delivery YY = Delivery status, see section Delivery status code values | AN400 | O | |
Sum of delivery and handling costs of the order | pmtq_sellercosts | The total sum of delivery and handling costs of the order. The amount must be presented with two decimals. The decimal delimiter is a comma, e.g. 7,40 | AN17 | O | |
Payment Method | pmtq_paymentmethod | Indicates what payment method the buyer chose. For available codes, see section Payment Method Codes. Important! Please do not use the values of the table above in production. Instead, retrieve official payment method codes and names using GetPaymentMethods.pmt API (see chapter Retrieve Available Payment Methods). | AN4 | O | |
Escrow is being used | pmtq_escrow | Tells whether escrow option is used with this payment. Values: Y/N The value is always Y for Satisfaction Guarantee payment services (e.g. Maksuturva Gold). Correspondingly, the value is always N for Direct payment services (e.g. eMaksut). | Satisfaction Guarantee payments = Y Direct payments = N | AN1 | O |
Verification info | pmtq_certification | Y = The payment has been verified. That is, the payer’s identity has been confirmed somehow. In case of Invoice and Part Payment payment methods, Svea Payments has information about the payer’s identity which is not the case with other payment methods. N = The payment has not been verified, or there is no verification information available. | Y,N | A1 | O |
Payment service response code 1 | pmtq_externalcode1 | Informal/additional payment service response information received from the external payment service provider in error situations. In case of Nets (formerly known as Luottokunta), the LKPRC code. In OK cases this could contain for example external payment service provider’s archive code of the payment. | AN50 | O | |
Payment service response code 2 | pmtq_externalcode2 | Informal/additional payment service response information received from the external payment service provider in error situations. In case of Nets (formerly known as Luottokunta), the LKSRC code. In OK cases this could contain for example external payment service provider’s archive code of the payment. | AN50 | O | |
Payment service response text | pmtq_externaltext | Informal/additional payment service response information received from the external payment service provider. Contains either information about successful payment or an error. If the external payment service provider does not provide this response information, this is either empty or it could contain for example external payment service provider’s archive code or some other unique id of the payment. | AN200 | O | |
Time when the buyer began the payment process | pmtq_paymentstarttimestamp | The time when payer transfered to the Payment Service. | dd.MM.yyyy hh:mm:ss | AN19 | O |
Payment date | pmtq_paymentdate | The date when payer paid. Or if it’s not available, the date when the money was found from Maksuturva’s Customer Assets bank account statement. | dd.MM.yyyy | AN10 | O |
Hash | pmtq_hash | Hash calculated from predefined response 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: pmtq_action pmtq_version pmtq_sellerid pmtq_id pmtq_amount pmtq_returncode pmtq_returntext pmtq_sellercosts (if available) pmtq_paymentmethod (if available) pmtq_escrow (if available) pmtq_certification (if available) pmtq_paymentdate (if available) | AN128 | C |
info
The note 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.