This API is available only by separate agreement

THE TOKENIZATION AND CARD CHARGING PROCESS

What does the tokenization of a card mean?

In the tokenization of a card the card number is stored in some system, that creates a separate identification tag for the card, called a token. The token is given to the web store’s use and it is valid at most for the time that the card is valid.

There are different algorithms and related requirements for the composition of tokens. In Svea Payments’ case no card information can be derived from the token as only the system where the actual card number is stored knows which token is related to which card.

Svea Payments utilizes its technical card payment processor’s (Payment Highway) tokenization service and card database that is used to store the card information of customers that have registered in the seller’s online service. If the tokenization service has been activated for the seller, card information can be stored when a payment is made on the payment form or the card can be registered without making an actual purchase at the same time.

If the card information is stored in connection with a purchase, 3D Secure authentication must be done if the card is to be used in recurring payments in the future. When the information is stored, the card database creates an individual identification tag (token) that is connected to the card number and then this token is passed on to the web store.

For the time being the supported uses of tokens are ”no-click” type card charge and recurring payments where the card is charged 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 the charging of the card was successful or not.

If the charging of the card with the token succeeds, a separate payment event is created in Svea Payments’ system. All the tasks that can be done with other card payments in the same service, can also be done with this new payment event.

The token that enables the charging of the card is valid at most for the time that the card is valid. After that the card must be tokenized again, i.e. a new tokenization request must be made where the buyer is authenticated and the card is tokenized.

Tokenization and charges in connection to purchases (not recurring payments)

Phases of the process:

The web store informs the cardholder before payment or registration of the card that the card number will be stored for future payments. The buyer needs to accept this.
The registration of the card is performed:
a. Payment + registration: The cardholder makes a payment with the card and 3DS authentication through for example the bank’s identification service is carried out. The card will also be registered for recurring payments.
b. OR only registration: The cardholder registers the card that also includes 3DS authentication for example through the bank’s identification service.
An individual identification tag (token) is created for the successful registration of a card, which Svea Payments then passes on 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 charge the card with the saved token when the customer/cardholder makes a purchase.

Different transaction types of charging the card

There are three basic types of charging the card with the token. PSD2 (The Second Payment Service Directive) requires the merchant to inform the card payment providers in the chain (processor, acquirer, card issuer..) about what type of card charging is being made. The basic types are:

MIT (Merchant-Initiated Transaction): “Random” merchant-initiated transactions; The merchant has something to bill from the cardholder and does that by initiating a card charge without immediate interaction with the cardholder.
MIT/Recurring: The card is charged with the same amount in a repeated manner with same frequency; for example monthly service fees.
CIT (Customer-Initiated Transaction): also called one-click transaction; The cardholder initiates the card charging by doing a purchase, being an active party in the process.

NOTE: Especially if the merchant uses the third type, CIT, they MUST indicate this in each credit card charge being made via Svea Payments' payment API. Technically this is done by using a specific pmt_version parameter value in the payment API call. Please see Using a token to charge the card below for more information.

Recurring payments and related contract

In case the seller tokenizes a card for automatic, for example monthly, recurring payments, there are certain special terms related to the tokenization and charging of the card:

the cardholder accepts the recurring payments contract between the cardholder and the seller before the tokenization and in this way gives the seller permission to charge the card in certain intervals
the seller sends the cardholder a verification of the contract
before every charge from the card the seller sends the cardholder 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 cardholder needs to accept before payment.
The registration of the card is performed:
a. Payment + registration: The cardholder makes a payment with the card and 3DS authentication through for example the bank’s identification service is carried out. The card will also be registered for recurring payments.
b. OR only registration: The cardholder registers the card that also includes 3DS authentication for example through the bank’s identification service.
An individual identification tag (token) is created for the successful registration of a card, which Svea Payments then passes on 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 cardholder a confirmation email. The email needs to include the following information:
- the text ”recurring charging of card”
- the amount to be charged
- how often the card will be charged
- 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 charging the card, 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 can be a maximum of one charge on the card per month and the recurring charge can not exceed the amount of the original payment.
The customer shall have the opportunity to cancel an upcoming or already made recurring charge.

Terms & Conditions and contract

Check Svea Payments’ and card companies’ terms and conditions related to recurring payments before taking the service in use. Pay special attention to chapter 8 in the document: Microsoft Word - Bambora - Card Not Present Instructions - ENG (FINAL 190813).docx (worldline.com)

The tokenization service and recurring payments will be added to the agreement between the web store and Svea Payments.

INTEGRATION OF INTERFACES AND TESTING

Registration of card (zero sum tokenization)

Skip to contents in this page

1 THE TOKENIZATION AND CARD CHARGING PROCESS
2 INTEGRATION OF INTERFACES AND TESTING

When the card 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 here.

The version information and pre-selected payment method should have the following values in the interface information:

pmt_version=4504
pmt_paymentmethod=FI50
pmt_action=TOKENIZE

All amount or sum fields should have the value 0,00. For example:

pmt_amount=0,00
pmt_sellercosts=0,00

With the parameters above, Svea Payments will instruct the buyer to perform the tokenization of the card. The card will not be charged 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>

Payments and card tokenization in connection to payment

NB! For normal card payments without the possibility for recurring payments, please use Svea Payments’ regular V4 interface (version 0004): Svea Payments’ integration guidelines.

When the card is to be charged and tokenized at the same time for a recurring payment without the separate approval or participation from the buyer, proceed as follows.

Payment and tokenization in connection to payment happens in the address:

TEST: http://test1.maksuturva.fi/NewPaymentExtended.pmt

PRODUCTION: https://www.maksuturva.fi/NewPaymentExtended.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

The version information and pre-selected payment method should have the following values in the interface information:

pmt_version=4304
pmt_paymentmethod=FI50

With the parameters above, Svea Payments will instruct the buyer to make the card payment and the card number will be tokenized. The card will only be charged if the tokenization is successful.

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 charge the card

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 here.

In the request, the version information and pre-selected payment method should have the following values in the interface information:

pmt_version
- For merchant-initiated (MIT) or recurring merchant-initiated (MIT/Recurring) transactions; pmt_version=4204
- For one-click/CIT-transactions; pmt_version=4104
pmt_paymentmethod=FI50
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.
The amount of an individual recurring payment cannot exceed the amount of the original payment.

For pmt_version 4204 (MIT or MIT/Recurring) the the card charging is usually either accepted or not. This is indicated in the response message. In some cases the charge can get timed out in some system in the chain and in such scenario the merchant’s system should do a payment status query later and/or accept payment confirmation call-back from Svea Payments.

For pmt_version 4104 (CIT / Customer-Initiated Transaction / one-click transaction) the process is usually the same as in MIT scenario but occasionally it gets more complex. In some cases the charging of the card is not directly accepted or refused but instead a scenario called soft fail is triggered. In this soft fail case of a CIT charging the following happens:

NewChargeWithTokenActionExtended responds with pmt_resultcode=01 and there is also an extra pmt_cardholderauthenticationurl parameter in the response.
If the merchant wishes the card payment to be accepted, the merchant has to redirect the cardholder to the given pmt_cardholderauthenticationurl to authenticate themself. The cardholder will then perform a strong customer authentication process as sometimes required by PSD2 and credit card rules.
After a successful authentication the card is charged by Svea Payments and the cardholder is redirected to the merchant’s OK URL passed to Svea in the original NewChargeWithTokenActionExtended request. In a unsuccessful scenario the cardholder is redirected to merchant’s Cancel or Error URL.

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>FI50</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_CARD_AUTHORIZATION_FAILED</pmt_errorcode>
  <pmt_errortext>Korttitapahtuman varmennus ei onnistunut.</pmt_errortext>
</chargeWithTokenResponse>

Error codes (pmt_errorcode) for a charge made with a token or for a status query:

Status query for card payment or charge 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 payment status query part

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:

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)

If, when retrieving the token information, you also want to make a test verification on the card, the following parameter can be added. With this parameter, Svea Payments’ system will perform a test verification on the card with a sum of 10 cents (0,10 EUR).

performOnlineAuthorizationCheck = true

If you want to make a test verification on the card with a larger sum, the following parameters can be used in addition to the previous one:

amountCents = sum of verification in cents, for example 1 EUR = 100
currencyCode = currency code of the verification, for example EUR

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 in personal test credentials part

General instructions for integration testing can be found in here.

Cards for testing that can be tokenized and used for recurring payments are listed in the guidelines of Payment Highway that provides the storing of card numbers and tokenization service: sandbox-credit-cards – API Reference (paymenthighway.io)

Svea Payments API

Card (tokenization and charging)