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 |
| Live Search | ||
|---|---|---|
|
| Table of Contents |
|---|
USING A FINNISH PERSONAL ID TO CREATE A NEW INVOICE
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=FI70
pmt_token=< the Finnish personal ID of buyer/invoice recipient >
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
Skip to contents in this page
| Table of Contents |
|---|
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>FI70</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 Invoice payment
Version 5 of Svea Payments’ normal status query interface can be used for the status query of tokenized payments or recurring payments made with tokens. General instructions can be found in here .
TEST: https://test1.maksuturva.fi/PaymentStatusQuery.pmt
PRODUCTION: https://payments.maksuturva.fi/PaymentStatusQuery.pmthere
In case the response includes the information pmtq_token, it is also added as last in the hash calculation. The response hash (pmtq_hash) will then include the following data:
pmtq_action
pmtq_version
pmtq_sellerid
pmtq_id
pmtq_amount
pmtq_returncode
pmtq_returntext
pmtq_sellercosts (if included in the response)
pmtq_paymentmethod (if included in the response)
pmtq_escrow (if included in the response)
pmtq_certification (if included in the response)
pmtq_paymentdate (if included in the response)
pmtq_token (if included in the response)
<secret key>
Below an example of a situation, where tokenization and payment has been performed, settlement of the transaction has been made to the web store and lastly, a status query has been done:
| Code Block | ||
|---|---|---|
| ||
<?xml version="1.0" encoding="UTF-8"?> <pmtq> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_amount>568,10</pmtq_amount> <pmtq_certification>N</pmtq_certification> <pmtq_escrow>N</pmtq_escrow> <pmtq_hash>***</pmtq_hash> <pmtq_id>1234567</pmtq_id> <pmtq_paymentdate>11.05.2016</pmtq_paymentdate> <pmtq_paymentmethod>FI70</pmtq_paymentmethod> <pmtq_paymentstarttimestamp>11.05.2016 12:45:07</pmtq_paymentstarttimestamp> <pmtq_returncode>40</pmtq_returncode> <pmtq_returntext>Compensated to the seller</pmtq_returntext> <pmtq_sellercosts>5,00</pmtq_sellercosts> <pmtq_sellerid>6234567890ABCDE</pmtq_sellerid> <pmtq_trackingcodes>[ODLVR|Kauppiaan oma toimitus|80]</pmtq_trackingcodes> <pmtq_version>0005</pmtq_version> </pmtq> |
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.