Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
| Note |
|---|
HOX This part of Invoicing with a Finnish personal ID |
USING A FINNISH PERSONAL ID TO CREATE A NEW PART PAYMENT
Live Search
| 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 | A2 | 0 | O |
Language | request_locale | fi, sv, en | 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 >(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:
| Code Block | ||
|---|---|---|
| ||
<?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 | ||
|---|---|---|
| ||
<?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.