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 Part Payment

Owned by Aslak Tolonen
Last updated: Oct 07, 2021 by Aleksi Ahonen
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 PART PAYMENT

Get Part Payment Plans

The payment plans can be retrieved (using either GET or POST) from address https://www.maksuturva.fi/GetSveaPaymentPlanInformation.pmt (or https://test1.maksuturva.fi/GetSveaPaymentPlanInformation.pmt in the testing environment).

 

 

Field

Input name

Value

Format

Min lenght

C/O

Field

Input name

Value

Format

Min lenght

C/O

Seller ID

gpp_sellerid

 

AN50

4

C

The total amount of the order that the buyer is about to pay, including all the costs.

gpp_amounttotal

e.g. 573,10

AN17

4

C

The currency of the total amount

gpp_amountcurrency

EUR, SEK, USD
default: EUR

A2

0

O

Language
This influences mostly error messages since the OK-response contains only numeric data.

request_locale

fi, sv, en
default: fi

A2

2

O

Response

The response (JSON document, UTF-8) is returned as direct response to the HTTP GET/POST request. the result contains a list of campaign objects with relevant information. For creating a S2S Part Payment, the CampaignCode value is the one you want to pass to the Payment API request, to select that campaign.

 

ResaultCode

ResultTest

Description

ResaultCode

ResultTest

Description

00

SUCCESS

OK

10

NO_PLANS_AVAILABLE

Usually because of too small total amount

99

ERROR

See below examples

 

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=FI71

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

  • pmt_campaigncode=< selected campaign code > (the value of the CampaignCode key for the selected campaign from the result data retrieved from Get Part Payment Plans )

 

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>FI71</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 Part Payment payment

Status queries are handled the same way as for S2S Invoice. See here for more information: Svea S2S invoice | Status query for Invoice payment

 

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