This API is available only by separate agreement

USING A FINNISH PERSONAL ID TO CREATE A NEW PART PAYMENT

Skip to contents in this page

1 USING A FINNISH PERSONAL ID TO CREATE A NEW PART PAYMENT
- 1.1 Get Part Payment Plans
  - 1.1.1 Response
- 1.2 Calling Payment API
  - 1.2.1 REQUEST:
  - 1.2.2 RESPONSE:
- 1.3 Status query for Part Payment payment
- 1.4 Testing

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

Field	Input name	Value	Format
Seller ID	`gpp_sellerid`		AN50
The total amount of the order that the buyer is about to pay, including all the costs. The amount must be presented with two decimals without thousands separator. The decimal delimiter is a comma, e.g. 94,80	`gpp_amounttotal`	e.g. 573,10	AN17
Optional: The currency of the total amount	`gpp_amountcurrency`	EUR, SEK, USD default: EUR	A3
Optional: Language This influences mostly error messages since the OK-response contains only numeric data.	`request_locale`	fi, sv, en default: fi	A2

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. When creating a S2S Part Payment, the CampaignCode value is the one you want to pass to the Payment API request described below, to select that campaign.

Success response example
gpp_amounttotal=573,10

{
	"campaigns": [
		{
			"MonthlyAnnuity": 191.03,
			"Description": "OSTA NYT, MAKSA 3KK KULUTTUA",
			"CreditCosts": 4.9,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 3,
			"NotificationFee": 0.0,
			"EffectiveInterestRatePercent": 5.28,
			"CampaignCode": "220100",
			"InterestRatePercent": 0.0,
			"TotalLoanCosts": 578.0,
			"Currency": "EUR",
			"ContractLengthInMonths": 3,
			"NrOfPaymentFreeMonths": 3,
			"InitialFee": 4.9
		},
		{
			"MonthlyAnnuity": 53.47,
			"Description": "ERÄMAKSU 12KK, 15.9%",
			"CreditCosts": 68.55,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 0,
			"NotificationFee": 1.5,
			"EffectiveInterestRatePercent": 23.61,
			"CampaignCode": "220115",
			"InterestRatePercent": 15.9,
			"TotalLoanCosts": 641.65,
			"Currency": "EUR",
			"ContractLengthInMonths": 12,
			"NrOfPaymentFreeMonths": 0,
			"InitialFee": 0.0
		},
		{
			"MonthlyAnnuity": 29.53,
			"Description": "ERÄMAKSU 24KK, 15.9%",
			"CreditCosts": 135.7,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 0,
			"NotificationFee": 1.5,
			"EffectiveInterestRatePercent": 23.51,
			"CampaignCode": "220120",
			"InterestRatePercent": 15.9,
			"TotalLoanCosts": 708.8,
			"Currency": "EUR",
			"ContractLengthInMonths": 24,
			"NrOfPaymentFreeMonths": 0,
			"InitialFee": 0.0
		},
		{
			"MonthlyAnnuity": 21.62,
			"Description": "ERÄMAKSU 36KK, 15.9%",
			"CreditCosts": 205.23,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 0,
			"NotificationFee": 1.5,
			"EffectiveInterestRatePercent": 23.26,
			"CampaignCode": "220125",
			"InterestRatePercent": 15.9,
			"TotalLoanCosts": 778.33,
			"Currency": "EUR",
			"ContractLengthInMonths": 36,
			"NrOfPaymentFreeMonths": 0,
			"InitialFee": 0.0
		},
		{
			"MonthlyAnnuity": 17.71,
			"Description": "ERÄMAKSU 48KK. 15.9%",
			"CreditCosts": 277.1,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 0,
			"NotificationFee": 1.5,
			"EffectiveInterestRatePercent": 23.01,
			"CampaignCode": "220105",
			"InterestRatePercent": 15.9,
			"TotalLoanCosts": 850.2,
			"Currency": "EUR",
			"ContractLengthInMonths": 48,
			"NrOfPaymentFreeMonths": 0,
			"InitialFee": 0.0
		},
		{
			"MonthlyAnnuity": 15.41,
			"Description": "ERÄMAKSU 60KK, 15.9%",
			"CreditCosts": 351.27,
			"PurchaseAmount": 573.1,
			"NrOfInterestFreeMonths": 0,
			"NotificationFee": 1.5,
			"EffectiveInterestRatePercent": 22.78,
			"CampaignCode": "220132",
			"InterestRatePercent": 15.9,
			"TotalLoanCosts": 924.37,
			"Currency": "EUR",
			"ContractLengthInMonths": 60,
			"NrOfPaymentFreeMonths": 0,
			"InitialFee": 0.0
		}
	],
	"documents":
	{
		"SveaPaymentsTermsOfService":
		{
			"text": "Käyttämällä Svea Paymentsin maksupalvelua hyväksyt palvelun käyttöehdot",
			"url": "https:\/\/www.svea.com\/globalassets\/finland\/documents\/maksupalvelut\/Kayttoehdot_ostaja.pdf"
		},
		"SveaPaymentsPrivacyPolicy":
		{
			"text": "Svea Paymentsin tietosuojaseloste",
			"url": "https:\/\/www.svea.com\/globalassets\/finland\/documents\/maksupalvelut\/Tietosuojaseloste_ostaja.pdf"
		},
		"SveaEkonomiPrivacyPolicy":
		{
			"text": "Svea Bankin tietosuojaseloste",
			"url": "https:\/\/www.svea.com\/globalassets\/finland\/documents\/maksupalvelut\/Svea_Bank_tietosuojaseloste.pdf"
		},
		"ConsumerCreditInfo":
		{
			"text": "Vakiomuotoiset eurooppalaiset kuluttajaluottotiedot",
			"url": "https:\/\/www.svea.com\/globalassets\/finland\/documents\/maksupalvelut\/Vakiomuotoiset_eurooppalaiset_kuluttajaluottotiedot.pdf"
		}
	}
}

Error response example
gpp_amounttotal=5,00 → too small total amount

{
	"errors":
	{
		"error": "No payment plans available for the given parameters."
	}
}

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 payment interface are here.
Please note that all mandatory parameters in the generic V4 payment API are also mandatory in S2S Part 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 described above)

RESPONSE:

Success response example

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

Error response example

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

Status query for Part Payment payment

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

Testing

This API can be tested in Svea Payments customer test environment (http://test1.maksuturva.fi) with individual test credentials.

Please see TESTING for instructions on the authentication of payments made in test environment.