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
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 )
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 | ||
|---|---|---|
|
| Table of Contents |
|---|
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.
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 (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.