{"type":"doc","content":[{"type":"layoutSection","marks":[{"type":"breakout","attrs":{"mode":"wide"}}],"content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"HOX This part of tokenization and charging of payment cards only by separate agreement","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"THE TOKENIZATION AND CARD CHARGING PROCESS","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"What does the tokenization of a card mean?","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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. ","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tokenization and charges in connection to purchases ","type":"text","marks":[{"type":"strong"}]},{"text":"(not recurring payments)","type":"text"}]},{"type":"paragraph","content":[{"text":"Phases of the process:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The registration of the card is performed:","type":"text"},{"type":"hardBreak"},{"text":"a. ","type":"text"},{"text":"Payment + registration: ","type":"text","marks":[{"type":"strong"}]},{"text":"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.","type":"text"},{"type":"hardBreak"},{"text":"b. ","type":"text"},{"text":"OR only registration:","type":"text","marks":[{"type":"strong"}]},{"text":" The cardholder registers the card that also includes 3DS authentication for example through the bank’s identification service.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The web store saves the token information and attaches it to the registered customer’s information.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The web store can charge the card with the saved token when the customer/cardholder makes a purchase.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Different transaction types of charging the card","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"There are three basic types of charging the card with the token. PSD2 (","type":"text"},{"text":"The Second Payment Service Directive","type":"text","marks":[{"type":"em"}]},{"text":") 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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MIT (Merchant-Initiated Transaction):","type":"text","marks":[{"type":"strong"}]},{"text":" “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. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MIT/Recurring:","type":"text","marks":[{"type":"strong"}]},{"text":" The card is charged with the same amount in a repeated manner with same frequency; for example monthly service fees.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CIT (Customer-Initiated Transaction): ","type":"text","marks":[{"type":"strong"}]},{"text":"also called one-click transaction; The cardholder initiates the card charging by doing a purchase, being an active party in the process.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text","marks":[{"type":"strong"}]},{"text":"pmt_version","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" parameter value in the payment API call. Please see ","type":"text","marks":[{"type":"strong"}]},{"text":"Using a token to charge the card ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"below for more information.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Recurring payments and related contract","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the seller sends the cardholder a verification of the contract","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"before every charge from the card the seller sends the cardholder a confirmation of an upcoming payment ","type":"text"},{"text":"beforehand","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"Phases of the process:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The web store shows the buyer the terms and conditions of recurring payments which the cardholder needs to accept before payment.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The registration of the card is performed:","type":"text"},{"type":"hardBreak"},{"text":"a. ","type":"text"},{"text":"Payment + registration: ","type":"text","marks":[{"type":"strong"}]},{"text":"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.","type":"text"},{"type":"hardBreak"},{"text":"b. ","type":"text"},{"text":"OR only registration:","type":"text","marks":[{"type":"strong"}]},{"text":" The cardholder registers the card that also includes 3DS authentication for example through the bank’s identification service.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The web store saves the token information and attaches it to the registered customer’s information.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The web store sends the cardholder a confirmation email.","type":"text","marks":[{"type":"strong"}]},{"text":" The email needs to include the following information:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the text ”recurring charging of card”","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the amount to be charged","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how often the card will be charged","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how long the contract for recurring payments is valid","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"if the amount to be charged is always the same fixed amount or whether it may vary","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Always before charging the card, ","type":"text"},{"text":"the web store will send a confirmation to the buyer in advance","type":"text","marks":[{"type":"strong"}]},{"text":", 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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The customer shall have the opportunity to cancel an upcoming or already made recurring charge.","type":"text"}]}]}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Terms & Conditions and contract","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Check Svea Payments’ and card companies’ terms and conditions related to recurring payments before taking the service in use. Pay special attention to chapter ","type":"text"},{"text":"5.3 ","type":"text","marks":[{"type":"strong"}]},{"text":"in the document: ","type":"text"},{"text":"https://www.bambora.com/globalassets/en/documents/english-version-new-general-terms-and-conditions/euroline---card-not-present-instructions-sv-eng-may-2015.pdf","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.bambora.com/globalassets/en/documents/english-version-new-general-terms-and-conditions/euroline---card-not-present-instructions-sv-eng-may-2015.pdf"}}]}]},{"type":"paragraph","content":[{"text":"The tokenization service and recurring payments will be added to the agreement between the web store and Svea Payments.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"INTEGRATION OF INTERFACES AND TESTING","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Registration of card","type":"text","marks":[{"type":"strong"}]},{"text":" (zero sum tokenization)","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Skip to contents in this page","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"8a8ce457-d31d-46df-baaa-768154487ba0"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"51c523c0-9b47-44b4-af46-1bde517e923e"}}]}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":65.0},"content":[{"type":"media","attrs":{"width":630,"id":"052f8a08-5b32-46e5-bb67-34e7331b8592","collection":"contentId-370802735","type":"file","height":425}}]},{"type":"paragraph","content":[{"text":"When the card is ","type":"text"},{"text":"tokenized","type":"text","marks":[{"type":"strong"}]},{"text":" for recurring payments without separate approval or participation from the buyer, proceed as follows.","type":"text"}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"paragraph","content":[{"text":"Tokenization happens in the address:","type":"text"}]},{"type":"paragraph","content":[{"text":"TEST:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"http://test1.maksuturva.fi/TokenizeExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/TokenizeExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":"PRODUCTION: ","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"https://www.maksuturva.fi/TokenizeExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.maksuturva.fi/TokenizeExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/1998888"}}]},{"text":".","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"The version information and pre-selected payment method should have the following values in the interface information:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_version=4504","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_paymentmethod=FI50","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_action=TOKENIZE","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"All amount or sum fields should have the value 0,00. For example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_amount=0,00","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_sellercosts=0,00","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"pmt_token","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" with which the web store can make additional charges. ","type":"text"},{"text":"pmt_token","type":"text","marks":[{"type":"em"}]},{"text":" is a part of the hash calculation at the end of the response, after ","type":"text"},{"text":"pmt_escrow","type":"text","marks":[{"type":"em"}]},{"text":" information:","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"response message","type":"text","marks":[{"type":"strong"}]},{"text":" hash that is transmitted through the browser includes the following data:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_action","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_version","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_id","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_reference","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_amount","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_currency","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_sellercosts","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_paymentmethod","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_escrow","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_token","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Payments and card tokenization in connection to payment","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":65.0},"content":[{"type":"media","attrs":{"width":633,"id":"2b6cb099-e999-42d8-95ed-f4399cd61cf9","collection":"contentId-370802735","type":"file","height":428}}]},{"type":"paragraph","content":[{"text":"NB! ","type":"text","marks":[{"type":"strong"}]},{"text":"For normal card payments without the possibility for recurring payments, please use Svea Payments’ regular V4 interface (version 0004): ","type":"text"},{"text":"Svea Payments’ integration guidelines","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/1998888"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"paragraph","content":[{"text":"When the card is to be ","type":"text"},{"text":"charged and tokenized at the same time","type":"text","marks":[{"type":"strong"}]},{"text":" for a recurring payment without the separate approval or participation from the buyer, proceed as follows.","type":"text"}]},{"type":"paragraph","content":[{"text":"Payment and tokenization in connection to payment happens in the address:","type":"text"}]},{"type":"paragraph","content":[{"text":"TEST:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"http://test1.maksuturva.fi/NewPaymentExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/NewPaymentExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":"PRODUCTION: ","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"https://www.maksuturva.fi/NewPaymentExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.maksuturva.fi/NewPaymentExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"The general instructions for the V4 interface can be found in ","type":"text"},{"text":"Svea Payments’ integration guidelines","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/1998888"}}]}]},{"type":"paragraph","content":[{"text":"The version information and pre-selected payment method should have the following values in the interface information:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_version=4304","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_paymentmethod=FI50","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"pmt_token","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" with which the web store can make additional charges. ","type":"text"},{"text":"pmt_token","type":"text","marks":[{"type":"em"}]},{"text":" is a part of the hash calculation at the end of the response, after ","type":"text"},{"text":"pmt_escrow","type":"text","marks":[{"type":"em"}]},{"text":" information:","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"response message","type":"text","marks":[{"type":"strong"}]},{"text":" hash that is transmitted through the browser includes the following data:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_action","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_version","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_id","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_reference","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_amount","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_currency","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_sellercosts","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_paymentmethod","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_escrow","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_token","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using a token to charge the card","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"REQUEST:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The V4 interface is used in a ","type":"text"},{"text":"server-to-server","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"TEST:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"http://test1.maksuturva.fi/NewChargeWithTokenActionExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/NewChargeWithTokenActionExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":"PRODUCTION:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"https://payments.maksuturva.fi/NewChargeWithTokenActionExtended.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"https://payments.maksuturva.fi/NewChargeWithTokenActionExtended.pmt"}}]}]},{"type":"paragraph","content":[{"text":"The general instructions for the V4 payment interface can be found in ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/1998888"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"In the request, the version information and pre-selected payment method should have the following values in the interface information:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_version","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For merchant-initiated (MIT)","type":"text","marks":[{"type":"strong"}]},{"text":" or recurring merchant-initiated (MIT/Recurring) transactions; pmt_version=","type":"text"},{"text":"4204","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For one-click/CIT-transactions;","type":"text","marks":[{"type":"strong"}]},{"text":" pmt_version=","type":"text"},{"text":"4104","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_paymentmethod=FI50","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmt_token=<","type":"text","marks":[{"type":"strong"}]},{"text":"the token that has previously been given to this buyer","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":">","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"In the payment message hash (","type":"text"},{"text":"pmt_hash","type":"text","marks":[{"type":"em"}]},{"text":"), ","type":"text"},{"text":"pmt_token","type":"text","marks":[{"type":"em"}]},{"text":" comes after the ","type":"text"},{"text":"pmt_sellercosts","type":"text","marks":[{"type":"em"}]},{"text":" data, before the row specific ","type":"text"},{"text":"pmt_row","type":"text","marks":[{"type":"em"}]},{"text":" data.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Requests for recurring payments are monitored and requests are blocked if the monthly allowed amount or number of transactions is exceeded.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The amount of an individual recurring payment cannot exceed the amount of the original payment.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For pmt_version 4204","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"MIT","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"For pmt_version 4104","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"CIT","type":"text","marks":[{"type":"strong"}]},{"text":" / 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 ","type":"text"},{"text":"soft fail","type":"text","marks":[{"type":"em"}]},{"text":" is triggered. In this soft fail case of a CIT charging the following happens:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"NewChargeWithTokenActionExtended ","type":"text","marks":[{"type":"em"}]},{"text":"responds with ","type":"text"},{"text":"pmt_resultcode=01","type":"text","marks":[{"type":"em"}]},{"text":" and there is also an extra ","type":"text"},{"text":"pmt_cardholderauthenticationurl ","type":"text","marks":[{"type":"em"}]},{"text":"parameter in the response.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the merchant wishes the card payment to be accepted, the merchant has to redirect the cardholder to the given ","type":"text"},{"text":"pmt_cardholderauthenticationurl","type":"text","marks":[{"type":"em"}]},{"text":" to authenticate","type":"text"},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"themself. The cardholder will then perform a strong customer authentication process as sometimes required by PSD2 and credit card rules.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"After a successful authentication the card is charged by Svea Payments and the cardholder is redirected to the merchant’s ","type":"text"},{"text":"OK URL ","type":"text","marks":[{"type":"em"}]},{"text":"passed to Svea in the original ","type":"text"},{"text":"NewChargeWithTokenActionExtended ","type":"text","marks":[{"type":"em"}]},{"text":"request. In a unsuccessful scenario the cardholder is redirected to merchant’s Cancel or Error URL.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"RESPONSE:","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Example of an OK response:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n NEW_PAYMENT_EXTENDED\n 4204\n 100000169\n 00000000001000002696\n 50,00\n EUR\n 5,00\n FI50\n Y\n 00\n **** \n","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Example of an error response:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"codeBlock","content":[{"text":"\n\n 99\n pmt_userlocale is invalid\n","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"2nd example of an error response:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n ERROR_CARD_AUTHORIZATION_FAILED\n Korttitapahtuman varmennus ei onnistunut.\n","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Error codes (pmt_errorcode) for a charge made with a token or for a status query:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"codeBlock","content":[{"text":"ALREADY_PAID = Order has already been paid\n\nERROR = Unknown error\n\nERROR_CARD_AUTHENTICATION_FAILED = 3DS authentication of card payment failed\n\nERROR_CARD_AUTHORIZATION_FAILED = Authorization of card payment failed\n\nERROR_CARD_AUTHORIZATION_TIMEOUT = Authorization or charging of card payment timed out\n\nERROR_CARD_TOKENIZATION_FAILED = Card can not be used for recurring payments\n\nERROR_IN_PAYMENT = Error in processing of payment\n\nERROR_IN_REQUEST_PAYER_DATA = Error(s) in information that can be edited by buyer \n\nERROR_IN_REQUEST_TECHNICAL_DATA = Error(s) in the technical data of the payment \n\nERROR_PAYMENT_INSTRUMENT_EXPIRED = The payment instrument is not valid\n\nERROR_PAYMENT_INSTRUMENT_LIMIT_EXCEEDED= The limit for the given payment instrument is exceeded\n\nERROR_PAYMENT_INSTRUMENT_NOT_FOUND = The given payment instrument can not be found\n\nERROR_PAYMENT_METHOD_NOT_AVAILABLE = The payment method chosen in the web store was not allowed\n\nEXTERNAL_SERVICE_DENIED = The chosen payment service denied the transaction\n\nEXTERNAL_SERVICE_ERROR = The chosen payment service gave an error response\n\nNOT_FOUND = Order can not be found\n\nPAYER_CHOSE_METHOD_AND_VANISHED = Payer chose a payment method but has not paid\n\nPAYER_INTERRUPTED = Payer cancelled the payment and returned to the web store\n\nPAYER_VANISHED = Payer vanished without paying\n\nWAITING = Waiting for information on possible payment","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Status query for card payment or charge made with a token","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"payment status query","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/2260997"}}]},{"text":" part","type":"text"}]},{"type":"paragraph","content":[{"text":"TEST","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"https://test1.maksuturva.fi/PaymentStatusQuery.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"https://test1.maksuturva.fi/PaymentStatusQuery.pmt"}}]}]},{"type":"paragraph","content":[{"text":"PRODUCTION","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"https://payments.maksuturva.fi/PaymentStatusQuery.pmt","type":"text","marks":[{"type":"link","attrs":{"href":"https://payments.maksuturva.fi/PaymentStatusQuery.pmt"}}]}]},{"type":"paragraph","content":[{"text":"In case the response includes the information pmtq_token, it is also added as last in the hash calculation. The response hash (","type":"text"},{"text":"pmtq_hash","type":"text","marks":[{"type":"em"}]},{"text":") will then include the following data:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_action","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_version","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_sellerid","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_id","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_amount","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_returncode","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_returntext","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_sellercosts ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_paymentmethod ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_escrow ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_certification ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_paymentdate ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtq_token ","type":"text"},{"text":" (if included in the response)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"","type":"text"}]}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"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:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n PAYMENT_STATUS_QUERY\n 568,10\n FI\n UNKNOWN\n DEBIT\n FI\n 0024\n VISA\n N\n N\n 100\n SUCCESS: CARD WAS DEBITED WITH A TOKEN\n ***\n 1234567\n 11.05.2016\n FI50\n 11.05.2016 12:45:07\n 40\n Compensated to the seller\n 5,00\n 6234567890ABCDE\n 57c48209-****-****-****-************\n N\n 1203,51\n EUR\n 573105,73\n 11\n 2017\n [ODLVR|Kauppiaan oma toimitus|80]\n 0005\n","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retrieving token information and event listing","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"REQUEST:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"TEST","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"http://test1.maksuturva.fi/api/token-query/","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/api/token-query/token.json"}}]},{"text":"token","type":"text","marks":[{"type":"strong"},{"type":"em"},{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/api/token-query/token.json"}}]},{"text":".json","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi/api/token-query/token.json"}}]},{"text":" ","type":"text"},{"text":"(or .xml)","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"PRODUCTION","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"https://payments.maksuturva.fi/api/token-query/","type":"text","marks":[{"type":"link","attrs":{"href":"https://payments.maksuturva.fi/api/token-query/token.json"}}]},{"text":"token","type":"text","marks":[{"type":"strong"},{"type":"em"},{"type":"link","attrs":{"href":"https://payments.maksuturva.fi/api/token-query/token.json"}}]},{"text":".json","type":"text","marks":[{"type":"link","attrs":{"href":"https://payments.maksuturva.fi/api/token-query/token.json"}}]},{"text":" ","type":"text"},{"text":"(or .xml)","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"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”).","type":"text"}]},{"type":"paragraph","content":[{"text":"The token information query requires only one mandatory parameter that is given as part of the request path:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"token = ","type":"text"},{"text":"token previously given to the web store","type":"text","marks":[{"type":"em"}]}]}]}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"fetchListOfPayments = true","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pmtId = ","type":"text"},{"text":"payment event identification pmt_id","type":"text","marks":[{"type":"em"}]},{"text":" (if you want to limit the results to one individual payment event)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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).","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"performOnlineAuthorizationCheck = true ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"amountCents = ","type":"text"},{"text":"sum of verification in cents, for example 1 EUR = 100","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"currencyCode = ","type":"text"},{"text":"currency code of the verification, for example EUR","type":"text","marks":[{"type":"em"}]}]}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"RESPONSE:","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Example of a JSON-response:","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{ \"amountCents\": 100\n \"cardBrowserCountry\": \"FI\"\n \"cardCategory\": \"UNKNOWN\"\n \"cardFundingType\": \"DEBIT\"\n \"cardIssuerCountry\": \"FI\"\n \"cardNumberMasked\": \"0024\"\n \"cardScheme\": \"VISA\"\n \"currencyCode\": \"EUR\"\n \"errorCode\": \"\"\n \"errorText\": \"\"\n \"fetchListOfSuccessfulDebitsDoneWithToken\": true\n \"onlineAuthorizationCheckAttempted\": false\n \"onlineAuthorizationCheckSuccess\": false\n \"performOnlineAuthorizationCheck\": false\n \"responseCode\": \"00\"\n \"successfulPayments\": [\n { \"amountCents\": 57310\n \"currencyCode\": \"EUR\"\n \"pmtId\": \"ZWYMEJZRHA8IW93Y6291\"\n \"sellerId\": \"MYYJA1\" }],\n \"waitingOrFailedPayments\": [\n { \"amountCents\": 0\n \"currencyCode\": \"EUR\"\n \"pmtId\": \"6JGZSIA9KY8LFN6RATMF\"\n \"sellerId\": \"MYYJA1\" }],\n \"token\": \"57c48209-****-****-****-************\"\n \"tokenAuthenticationRequired\": false\n \"tokenDebitLimitCents\": 200000\n \"tokenDebitLimitCentsMonthly\": 500000\n \"tokenDebitLimitCurrency\": \"EUR\"\n \"tokenExpirationMonth\": \"11\"\n \"tokenExpirationYear\": \"2017\" }","type":"text"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Hash calculation","type":"text"}]},{"type":"paragraph","content":[{"text":"General instructions for hash calculation can be found in ","type":"text"},{"text":"hash generation","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/262253"}}]},{"text":" part","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Testing","type":"text"}]},{"type":"paragraph","content":[{"text":"Recurring payments can be tested in Svea Payments’ customer test environment (","type":"text"},{"text":"http://test1.maksuturva.fi","type":"text","marks":[{"type":"link","attrs":{"href":"http://test1.maksuturva.fi"}}]},{"text":") with personal test credentials. Instructions for ordering the credentials can be found in ","type":"text"},{"text":"personal test credentials","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/33238"}}]},{"text":" part","type":"text"}]},{"type":"paragraph","content":[{"text":"General instructions for integration testing can be found in ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DOCSLEGACY/pages/557057"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"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: ","type":"text"},{"text":"https://paymenthighway.fi/dev/#sandbox-credit-cards","type":"text","marks":[{"type":"link","attrs":{"href":"https://paymenthighway.fi/dev/#sandbox-credit-cards"}}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]}],"version":1}

Browser not supported