Versions Compared

Old Version 4

changes.mady.by.user Aslak Tolonen

Saved on

compared with

New Version Current

changes.mady.by.user Aleksi Ahonen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

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

Skip to contents in this page

Table of Contents

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

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

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 / payment option >(this value is selected from 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:

Live Search
placeholdersearch

Table of Contents

Example of an OK response:

Code Block
languagexml
<?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:

Code Block
languagexml
<?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:

Code Block
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: https://sveapayments.atlassian.net/wiki/spaces/DOCS/pages/374046721/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.

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

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

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 (XML document, UTF-8) is returned as direct response to the HTTP GET/POST request. The contents are best described through an example.

ResaultCode

ResultTest

Description

00

SUCCESS

OK

10

NO_PLANS_AVAILABLE

Usually because of too small total amount

99

ERROR

See below examples

Hint / Tips

Let's assume webstore wants to display "from 31,00 € per month" on the product sheet. This price information can be found from the first payment plan line of the longest payment plan. That is, start by locating the longest payment plan i.e. the <PaymentPlan> with the largest <PaymentPlanLineCount> value. Then locate the first <PaymentPlanLine> and pick the <Total> value from it. In the example below, the longest payment plan is 24 months (PaymentPlanLineCount=24). The value to pick is emphasized with blue color.