This documentation is deprecated and only available for supporting old/legacy integrations using for example hashes.
New documentation can be found here: Home
Svea Invoice tokenization and charging
- Aleksi Ahonen
- Viivi Ahlqvist
HOX This part is only by separate agreement
THE TOKENIZATION AND RECURRING INVOICING PROCESS
What does the tokenization of a personal ID mean?
In the tokenization of a personal ID, the ID is stored in some system, that creates a separate identification tag for the ID, called a token. The token is given to the web store’s use and it is valid for a pre-defined time period.
There are different algorithms for the composition of tokens. In Svea Payments case no information can be derived from the token as only the system where the actual personal ID is stored knows which token is related to which personal ID. If the tokenization service has been activated for the seller, personal ID must be registered without making an actual purchase at the same time. The token created in the process can then be used to create actual orders / invoices.
For the time being the supported use of tokens is “no-click” type of invoice creation and recurring invoicing where an invoice is created in a recurring fashion based on the request of the web store, without participation from the buyer. The web store passes on the charge request to Svea Payments payment interface and Svea Payments responds directly to the web store whether an invoice creation was successful or not.
If the invoice creation with the token succeeds, a separate payment event (or order) is created in Svea Payments system. All the tasks that can be done with other invoice type of payments in the same service, can also be done with this new payment event.
The token that enables the creation of invoices is valid for a certain time period. After that the personal ID must be tokenized again, i.e. a new tokenization request must be made where the buyer is authenticated and the personal ID is tokenized.
Tokenization and creating invoices
Phases of the process:
The web store informs the person before payment or registration of the personal ID that the personal ID will be stored for future payments. The buyer needs to accept this.
The registration of the personal ID is performed: The buyer registers their personal ID by authenticating with a strong authentication method, for example their bank’s identification service (TUPAS).
An individual identification tag (token) is created for the successful registration. Svea Payments passes the token in the response message to the web store.
The web store saves the token information and attaches it to the registered customer’s information.
The web store can create new invoices with the saved token when the customer makes a purchase.
Recurring invoices and related contract
In case the seller tokenizes a personal ID for automatic, for example monthly, recurring payments, there are certain special terms related to the tokenization and creating new invoices:
the buyer accepts the recurring payments contract between the buyer and the seller before the tokenization and in this way gives the seller permission to use their personal ID for creating new invoices in certain intervals
the seller sends the buyer a verification of the contract
for every new invoice, the seller sends the buyer a confirmation of an upcoming payment beforehand
Phases of the process:
The web store shows the buyer the terms and conditions of recurring payments which the buyer needs to accept before payment.
The registration of the personal ID is performed: The buyer registers their personal ID by authenticating with a strong authentication method, for example their bank’s identification service (TUPAS).
An individual identification tag (token) is created for the successful registration. Svea Payments passes the token in the response message to the web store.
The web store saves the token information and attaches it to the registered customer’s information.
The web store sends the buyer a confirmation email about the invoicing contract that was just made. The email must include at least the following information:
indication that recurring invoices will be created
the amount to be invoiced for each recurring invoice
how often invoices will be created
how long the contract for recurring payments is valid
if the amount to be charged is always the same fixed amount or whether it may vary
Always before creating a new invoice, the web store will send a confirmation to the buyer in advance, through which the web store informs its customer of an upcoming charge (amount and date). In principle, there should be a maximum of one new recurring invoice per month.
The buyer shall have the opportunity to cancel an upcoming or already made recurring charge.
Terms & Conditions and contract
Check Svea Payments terms and conditions related to recurring payments before taking the service in use.
The tokenization service and recurring payments will be added to the subscription agreement between the web store and Svea Payments.
INTEGRATION OF INTERFACES AND TESTING
Registration of a personal ID (zero sum tokenization)
Skip to contents in this page
When the personal ID is tokenized for recurring payments without separate approval or participation from the buyer, proceed as follows.
Tokenization happens in the address:
TEST: http://test1.maksuturva.fi/TokenizeExtended.pmt
PRODUCTION: https://www.maksuturva.fi/TokenizeExtended.pmt
Svea Payments V4 interface is used so that the buyer enters the payment service in the browser. The web store submits the tokenization information through the browser as FORM parameters in the HTTP POST request. The general instructions for the V4 interface can be found in Svea Payments integration guidelines: http://docs.maksuturva.fi/en/html/pages/3_3_payment.html
The version information and pre-selected payment method should have the following values in the interface information:
pmt_version=4504
pmt_paymentmethod=FI70
pmt_action=TOKENIZE
All amount or sum fields should have the default value 200,00. This value is used for an initial credit check. For example:
pmt_amount=200,00
pmt_sellercosts=0,00
With the parameters above, Svea Payments will instruct the buyer to perform the tokenization of the personal ID. No invoice will be created at this time.
The response that the web store gets through the browser will include, in addition to the other mandatory payment interface V4 OK-response data, the information pmt_token with which the web store can make additional charges. pmt_token is a part of the hash calculation at the end of the response, after pmt_escrow information:
The response message hash that is transmitted through the browser includes the following data:
pmt_action
pmt_version
pmt_id
pmt_reference
pmt_amount
pmt_currency
pmt_sellercosts
pmt_paymentmethod
pmt_escrow
pmt_token
<secret key>
Using a token to create a new invoice
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.maksuturva.fi/en/html/pages/3_3_payment.html
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 token that has previously been given to this buyer>
In the payment message hash (pmt_hash), pmt_token comes after the pmt_sellercosts data, before the row specific pmt_row data.
Requests for recurring payments are monitored and requests are blocked if the monthly allowed amount or number of transactions is exceeded.
RESPONSE:
Example of an OK response:
<?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:
<?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>2nd example of an error response:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
<pmt_errorcode>ERROR_PAYMENT_INSTRUMENT_EXPIRED</pmt_errorcode>
<pmt_errortext>The payment instrument is not valid.</pmt_errortext>
</chargeWithTokenResponse>Error codes (pmt_errorcode) for a charge made with a token or for a status query:
Status query for Invoice payment or Invoice made with a token
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 Svea Payments integration guidelines: http://docs.maksuturva.fi/en/html/pages/3_4_payment_status_query.html
TEST: https://test1.maksuturva.fi/PaymentStatusQuery.pmt
PRODUCTION: https://payments.maksuturva.fi/PaymentStatusQuery.pmt
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>
There will be fields related to the token in the status query response of a transaction that has included tokenization. In addition, fields related to the card will be found in status queries of card payments in general. 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. NOTE: This example is for tokenized card instead of personal ID:
Retrieving token information and event listing
The information of a created token can be fetched through a REST-type query interface. The response will be provided in JSON or XML format.
REQUEST:
TEST: http://test1.maksuturva.fi/api/token-query/token.json (or .xml)
PRODUCTION: https://payments.maksuturva.fi/api/token-query/token.json (or .xml)
The request requires authorization with the seller id (sellerId) and secret key (secret key / shared secret). Authorization is done by submitting the required information as standard HTTP Basic AUTH HTTP-headers (”Authorization”).
The token information query requires only one mandatory parameter that is given as part of the request path:
token = token previously given to the web store
If at the same time you want a list of previously successful as well as failed payments made with the token or the situation of an individual payment event, one or both of the following can be added:
fetchListOfPayments = true
pmtId = payment event identification pmt_id (if you want to limit the results to one individual payment event)
RESPONSE:
Example of a JSON-response:
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.