Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

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

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

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

<?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_resultcode) for a charge made with a token or for a status query:

ALREADY_PAID                           = Order has already been paid

ERROR                                  = Unknown error

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_LIMIT_EXCEEDED= The limit for the given payment instrument is exceeded

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

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/1657013176/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.

  • No labels

Svea Payments Oy
info.payments@svea.fi
+358 9 4241 7050 (weekdays 8:00 - 16:00)
Saavutettavuusseloste