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.

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:

- - - - -

- 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 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)

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=4204
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.

RESPONSE:

Example of an OK response:

Code Block

language	xml

<?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:

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>

2nd example of an error response:

Code Block

language	xml

<?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:

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

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<pmtq>
  <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action>
  <pmtq_amount>568,10</pmtq_amount>
  <pmtq_card_browser_country>FI</pmtq_card_browser_country>
  <pmtq_card_category>UNKNOWN</pmtq_card_category>
  <pmtq_card_funding_type>DEBIT</pmtq_card_funding_type>
  <pmtq_card_issuer_country>FI</pmtq_card_issuer_country>
  <pmtq_card_number_masked>0024</pmtq_card_number_masked>
  <pmtq_card_scheme>VISA</pmtq_card_scheme>
  <pmtq_certification>N</pmtq_certification>
  <pmtq_escrow>N</pmtq_escrow>
  <pmtq_externalcode1>100</pmtq_externalcode1>
  <pmtq_externaltext>SUCCESS: CARD WAS DEBITED WITH A TOKEN</pmtq_externaltext>
  <pmtq_hash>***</pmtq_hash>
  <pmtq_id>1234567</pmtq_id>
  <pmtq_paymentdate>11.05.2016</pmtq_paymentdate>
  <pmtq_paymentmethod>FI50</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_token>57c48209-****-****-****-************</pmtq_token>
  <pmtq_token_authentication_required>N</pmtq_token_authentication_required>
  <pmtq_token_debit_limit>1203,51</pmtq_token_debit_limit>
  <pmtq_token_debit_limit_currency>EUR</pmtq_token_debit_limit_currency>
  <pmtq_token_debit_limit_monthly>573105,73</pmtq_token_debit_limit_monthly>
  <pmtq_token_expiration_month>11</pmtq_token_expiration_month>
  <pmtq_token_expiration_year>2017</pmtq_token_expiration_year>
  <pmtq_trackingcodes>[ODLVR|Kauppiaan oma toimitus|80]</pmtq_trackingcodes>
  <pmtq_version>0005</pmtq_version>
</pmtq>

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:

Code Block

language	json

{ "amountCents": 100
  "cardBrowserCountry": "FI"
  "cardCategory": "UNKNOWN"
  "cardFundingType": "DEBIT"
  "cardIssuerCountry": "FI"
  "cardNumberMasked": "0024"
  "cardScheme": "VISA"
  "currencyCode": "EUR"
  "errorCode": ""
  "errorText": ""
  "fetchListOfSuccessfulDebitsDoneWithToken": true
  "onlineAuthorizationCheckAttempted": false
  "onlineAuthorizationCheckSuccess": false
  "performOnlineAuthorizationCheck": false
  "responseCode": "00"
  "successfulPayments": [
    { "amountCents": 57310
      "currencyCode": "EUR"
      "pmtId": "ZWYMEJZRHA8IW93Y6291"
      "sellerId": "MYYJA1" }],
  "waitingOrFailedPayments": [
    { "amountCents": 0
      "currencyCode": "EUR"
      "pmtId": "6JGZSIA9KY8LFN6RATMF"
      "sellerId": "MYYJA1" }],
  "token": "57c48209-****-****-****-************"
  "tokenAuthenticationRequired": false
  "tokenDebitLimitCents": 200000
  "tokenDebitLimitCentsMonthly": 500000
  "tokenDebitLimitCurrency": "EUR"
  "tokenExpirationMonth": "11"
  "tokenExpirationYear": "2017" }

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

Versions Compared

Old Version 4

New Version 5

Key

THE TOKENIZATION AND CARD CHARGING PROCESS

What does the tokenization of a card mean?

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

Recurring payments and related contract

Terms & Conditions and contract

INTEGRATION OF INTERFACES AND TESTING

Registration of card (zero sum tokenization)

Payments and card tokenization in connection to payment

Using a token to charge the card

Status query for card payment or charge made with a token

Retrieving token information and event listing

Hash calculation

Testing

Page Comparison

Versions Compared

Old Version 4

New Version 5

Key

THE TOKENIZATION AND CARD CHARGING PROCESS

What does the tokenization of a card mean?

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

Recurring payments and related contract

Terms & Conditions and contract

INTEGRATION OF INTERFACES AND TESTING

Registration of card (zero sum tokenization)

Payments and card tokenization in connection to payment

Using a token to charge the card

Status query for card payment or charge made with a token

Retrieving token information and event listing

Hash calculation

Testing