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

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

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:

Live Searchplaceholder
search
Table of Contents

Example of an OK response:

Code Block

language	xml

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

language	xml

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

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

Versions Compared

Old Version 6

New Version Current

Key

USING A FINNISH PERSONAL ID TO CREATE A NEW PART PAYMENT

Get Part Payment Plans

Response

Calling Payment API

Status query for Part Payment payment

Hash calculation

Testing

Get Part Payment Plans

Response

Page Comparison

Versions Compared

Old Version 6

New Version Current

Key

USING A FINNISH PERSONAL ID TO CREATE A NEW PART PAYMENT

Get Part Payment Plans

Response

Calling Payment API

Status query for Part Payment payment

Hash calculation

Testing

Get Part Payment Plans

Response