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:

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

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

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

4. The web store saves the token information and attaches it to the registered customer’s information.

5. 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:

1. The web store shows the buyer the terms and conditions of recurring payments which the cardholder needs to accept before payment.

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

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

4. The web store saves the token information and attaches it to the registered customer’s information.

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

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

7. 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 5.3 in the document: https://www.bambora.com/globalassets/en/documents/english-version-new-general-terms-and-conditions/euroline---card-not-present-instructions-sv-eng-may-2015.pdf

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)

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

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 authenticatethemself. 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:

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>

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:

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:  https://paymenthighway.fi/dev/#sandbox-credit-cards