Versions Compared

Old Version 2

changes.mady.by.user Aleksi Ahonen

Saved on

compared with

New Version 3

changes.mady.by.user Aleksi Ahonen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

HOX This part of Invoicing with a Finnish personal ID
through Svea’s Webpay-interface is used only by separate agreement

Live Search
placeholdersearch

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

RESPONSE:

Example of an OK response:

Code Block
languagexml
<?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
languagexml
<?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
languagexml
<?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.