This documentation is deprecated and only available for supporting old/legacy integrations using for example hashes.

New documentation can be found here: Home



Svea S2S invoice

Owned by Aleksi Ahonen
Last updated: Oct 07, 2021
3 min read

HOX This part of Invoicing with a Finnish personal ID
through Svea’s Webpay-interface is used only by separate agreement

USING A FINNISH PERSONAL ID TO CREATE A NEW INVOICE

 

Calling Payment API

REQUEST:

The V4 interface is used in a server-to-server type fashion. The web store transfers the payment data directly as an HTTP POST -request. The web store can choose which http client product to use for this.

TEST: http://test1.maksuturva.fi/NewChargeWithTokenActionExtended.pmt

PRODUCTION: https://payments.maksuturva.fi/NewChargeWithTokenActionExtended.pmt

The general instructions for the V4 payment interface can be found in Svea Payments’ integration guidelines: http://docs.sveapayments.fi/api/payment-api/payment/.

In the request, the version information and pre-selected payment method should have the following values in the interface information:

  • pmt_version=4204

  • pmt_paymentmethod=FI70

  • pmt_token=< the Finnish personal ID of buyer/invoice recipient >

 

AUTHENTICATING THE REQUEST:

You can use one of the following:

  • Hash value:

    • pmt_hash: Calculate hash value as described in general instructions for the V4 payment interface.

    While creating the string to be hashed, add pmt_token value after the pmt_sellercosts data

  • HTTP Basic Auth:

    • Use merchant's seller_id as the username and secret key as the password for a standard HTTP Basic Auth Header.

    • Exclude parameters pmt_hash and pmt_hashversion from the request

RESPONSE:

Example of an OK response:

 

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <chargeWithTokenResponse>     <pmt_action>NEW_PAYMENT_EXTENDED</pmt_action>     <pmt_version>4204</pmt_version>     <pmt_id>100000169</pmt_id>     <pmt_reference>00000000001000002696</pmt_reference>     <pmt_amount>50,00</pmt_amount>     <pmt_currency>EUR</pmt_currency>     <pmt_sellercosts>5,00</pmt_sellercosts>     <pmt_paymentmethod>FI70</pmt_paymentmethod>     <pmt_escrow>Y</pmt_escrow>     <pmt_resultcode>00</pmt_resultcode>     <pmt_hash>**** </pmt_hash> </chargeWithTokenResponse>

Example of an error response:

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <chargeWithTokenResponse>   <pmt_resultcode>99</pmt_resultcode>   <error name="pmt_userlocale" type="field">pmt_userlocale is invalid</error> </chargeWithTokenResponse>

Error codes (pmt_errorcode) for a charge made with a token or for a status query:

ALREADY_PAID                           = Order has already been paid ERROR                                  = Unknown error ERROR_CARD_AUTHENTICATION_FAILED       = 3DS authentication of card payment failed ERROR_CARD_AUTHORIZATION_FAILED        = Authorization of card payment failed ERROR_CARD_AUTHORIZATION_TIMEOUT       = Authorization or charging of card payment timed out ERROR_CARD_TOKENIZATION_FAILED         = Card can not be used for recurring payments ERROR_IN_PAYMENT                       = Error in processing of payment ERROR_IN_REQUEST_PAYER_DATA            = Error(s) in information that can be edited by buyer ERROR_IN_REQUEST_TECHNICAL_DATA        = Error(s) in the technical data of the payment ERROR_PAYMENT_INSTRUMENT_EXPIRED       = The payment instrument is not valid ERROR_PAYMENT_INSTRUMENT_LIMIT_EXCEEDED= The limit for the given payment instrument is exceeded ERROR_PAYMENT_INSTRUMENT_NOT_FOUND     = The given payment instrument can not be found ERROR_PAYMENT_METHOD_NOT_AVAILABLE     = The payment method chosen in the web store was not allowed EXTERNAL_SERVICE_DENIED                = The chosen payment service denied the transaction EXTERNAL_SERVICE_ERROR                 = The chosen payment service gave an error response NOT_FOUND                              = Order can not be found PAYER_CHOSE_METHOD_AND_VANISHED        = Payer chose a payment method but has not paid PAYER_INTERRUPTED                      = Payer cancelled the payment and returned to the web store PAYER_VANISHED                         = Payer vanished without paying WAITING                                = Waiting for information on possible payment

Status query for Invoice payment

Version 5 of Svea Payments’ normal status query interface can be used for the status query of tokenized payments or recurring payments made with tokens. General instructions can be found in here .

TEST: https://test1.maksuturva.fi/PaymentStatusQuery.pmt

PRODUCTION: https://payments.maksuturva.fi/PaymentStatusQuery.pmthere

In case the response includes the information pmtq_token, it is also added as last in the hash calculation. The response hash (pmtq_hash) will then include the following data:

  • pmtq_action

  • pmtq_version

  • pmtq_sellerid

  • pmtq_id

  • pmtq_amount

  • pmtq_returncode

  • pmtq_returntext

  • pmtq_sellercosts  (if included in the response)

  • pmtq_paymentmethod  (if included in the response)

  • pmtq_escrow  (if included in the response)

  • pmtq_certification  (if included in the response)

  • pmtq_paymentdate  (if included in the response)

  • pmtq_token  (if included in the response)

  • <secret key>

 

Below an example of a situation, where tokenization and payment has been performed, settlement of the transaction has been made to the web store and lastly, a status query has been done:

Hash calculation

General instructions for hash calculation can be found in hash generation part

Testing

Recurring payments can be tested in Svea Payments customer test environment (http://test1.maksuturva.fi) with personal test credentials. Instructions for ordering the credentials can be found personal test credentials part

General instructions for integration testing can be found in here.

 

This documentation is deprecated and only available for supporting old/legacy integrations using for example hashes.

New documentation can be found here: Home