Skip to main content

E-Commerce V1 Form Specification

Introduction​

TPS contains multiple forms and messaging logic for processing different tasks:

  • pan token generation;
  • performing payments;
  • saving card data (for recurring payments);
  • performing recurring payments (with pre-defined card data). Those forms are separate HTML pages, which can be loaded inside Ticketing System's html page ("parent"), inside an iframe.

The E-Commerce forms are able to communicate with TPS for processing the tokenisation and payments, but require HMAC from the "parent" (since HMAC calculation is done with a shared secret key, which needs to be kept secret).

E-Commerce application mock page for testing and integration purposes: https://ecomm.payments.test.sfey.com/ps_mock/index.html#

In E-Commerce source package, there is an example of the TS "parent" page ("ps_mock/index.html"). It can be used to understand the message flow.

NB! In the example, shared secret key is stored in "ps_mock/index.html" file. In actual systems, the key should be securely stored and never be available in front-end components.

Endpoint: PAN number tokenization endpoint

URLs:

Processing flow​

E-Commerce interface uses HMAC verification to verify the integrity of the requests received.

Ticketing System (TS) is required to calculate HMAC value for some specified data (specific for each form) and provide the HMAC to Transit Payment System (TPS) E-Commerce HTML form.

When the form data is submitted, the HMAC is added to request parameters, which are sent to TPS.

When TPS receives the request, it calculates HMAC value based on the request fields and compares it against the HMAC received.

Both TPS and TS systems use a shared secret key for HMAC calculation, which is stored securely in both systems.

For HMAC calculation, a SHA-256 algorithm is used.

The message flow between different components is shown on the following sequence diagram. Please note that the messaging between Ticketing System components ("parent" html form and the system backend) can be implemented differently than shown on the diagram, but the following is required for security purposes:

  • shared secret key is not available in the html component for HMAC calculation;
  • transaction status is requested from TS backend after successful response is received from TPS backend (17. on diagram)

image.png Message flow for transaction submission - sequence diagram

Messaging specification​

Form creation​

In the message flow sequence diagram step (1) Ticketing System "parent" html form should first set up event listener for the main window with the JavaScript EventTarget.addEventListener() method. This event listener should listen for events where event data contains object with the field ready. If this field value is true then listener should perform E-commerce html form initialisation (see the next chapter).

After the listener is set up "parent" form should create an E-Commerce HTML form by setting document's IFRAME element SRC attribute to the appropriate E-commerce HTML form URL. The E-commerce HTML form URL consists of two parts:

{baseurl}#/{formName}

Base URL depends from the TPS environment and the {formName} can be one of the following:

formNameForm name
pan-token-generationGenerate PAN token

Form initialization​

During the form creation Ticketing System "parent" form should create event listener for the main window with the JavaScript EventTarget.addEventListener() method. When this listener receives an event with the event data containing an object with the field ready and this field value is true, then form should start initialisation of the E-commerce HMTL Form via JavaScript Window.postMessage() method. This method should be called on step (8) on the message flow sequence diagram (see above). Message should be JavaScript object and can contain the following fields:


{
    lang: "en",
    hostApp: "default",
    panFormatting: "disabled",
    transactionId: 1234567890,
    terminalId: "ABS00003",
    companyId: "23300001",
    additionalCompanyIds: ["23300002", "23300004"],
    useNewCardTokenForm: true,
    clientId: 11,
    amount: 1500,
    currencyCodeNum: 978,
    datetime: "2017-07-03T10:28:44.073",
    hmacFields: ["transactionId", "terminalId", "companyId", "datetime", "amount", "currencyCodeNum", "hmacFields"],
    hmac: "150L5Vp9MNVzCSzwrp2RNIBkpirxt9/utTkGbD17ZP4="
}

Fields lang, hostApp, panFormatting, transactionId, companyId, datetime, hmacFields and hmac should be always present. Presence of the other fields depends of the form type:

FormAdditional items
pan-token-generationadditionalCompanyIds, useNewCardTokenForm
psc-payment-formterminalId, clientId, amount, currencyCodeNum
recurring-payment.
save-cardclientId
.terminalId, amount, currencyCodeNum

Field descriptions:

  • lang - Form language. Currently supported languages are: "en", "et", "ru", "fi", "sv".
  • hostApp - Form design template. Currently implemented templates are: "default", "tallinn", "parnu", "tartu", "bo", "emv", "elron", "kolumbus", "vastmanland", "sörmland", "klaipeda", "imatra".
  • panFormatting - If PAN field value should be formatted. Value should be either "disabled" or "enabled.
  • transactionId (int64/uuid) - Unique transaction id for this company. Based by this ID company is able to link this form and PAN token received from the TPS.
  • terminalId - Terminal ID used for making e-commerce payment.
  • companyId - Company ID registered in the TPS.
  • additionalCompanyIds - Additional company IDs when PAN tokenization form should return to the ticketing system also PAN tokens for additional companies too.
  • useNewCardTokenForm - When true then new PAN tokenization form will be used (asks additionally card expiry date and cardholder name and performs 3DS authentication)
  • clientId - Cardholder ID in the ticketing system
  • amount - E-commerce transaction amount in cents
  • currencyCodeNum - E-commerce transaction amont currency code (ISO 4217 numeric code)
  • datetime - Transaction date and time
  • hmacFields - Fields used for HMAC calculation
  • hmac - Calculated HMAC

Form Customization​

The design of the PAN entry form can be customized by creating a new hostApp form design template. Current design templates can be seen there: https://ecomm.payments.test.sfey.com/ps_mock/index.html .

You can switch between different design forms via the second select-box at the top of the page:

Screenshot 2024-04-26 at 10.07.14.png

If you need a new design template, please provide the following information:

  1. Which existing design template should be used as a basis.
  2. If only color changes are needed, provide new CSS color values for this template.
  3. If structural changes to the form are also needed, please create a Figma design for it.

Card Tokenization Result​

Sfey TPS will tokenize the bank card PAN number inserted into the e-commerce tokenization form and send the response to the URL provided by the Ticketing System.

MethodResource
PUTURL provided by Ticketing System
{
     "epanToken": "edd8eb187b2152a2f00f4df6ce7223fd4117a7a25638a8eb7ca6ab7a6f8b1422",
     "additionalEpanTokens": [],
     "parToken": null,
     "iccPkCertHash": null,
     "additionalIccPkCertHashes": [],
     "transactionId": 53026437,
     "transactionUuid": "c77ec9e4-27f9-52f6-ba85-50f3802a8e9d",
     "authResult": null,
     "fundingToken": "3ccfef41f63c8356d264cef234c711932b6cc5534db18687fe5b479eafdc8444",
     "additionalFundingTokens": [],
     "scheme": "MASTERCARD"
}

Field descriptions:

  • epanToken - tokenized PAN number that was inserted by the customer
  • additionalEpanTokens - card PAN tokens from the organisations listed in the request field additionalCompanyIds + PAN tokens of related cards from the main organisation and also from the organisations listed in the request field additionalCompanyIds
  • parToken - tokenized PAR number of the inserted card
  • iccPkCertHash - SHA256 hash calculated from the payment card ICC Public Key Certificate (tag 9F46 on the card)
  • additionalIccPkCertHashes - additional organization hashes if multiple organization data is requested requested
  • transactionId - can be ignored
  • transactionUuid - UUID value of the transaction
  • authResult - 3D Secure result if strong authentication is configured (“null”, “ok”, “notEnrolled”, “failed”)
  • fundingToken - tokenized PAN of the funding card. In case of VISA cards it will be the PAR token. In case of - Mastercard & Maestro cards it will be the token of the funding card (e.g. plastic card). Funding token value is the same for all linked cards
  • additionalFundingTokens - additional funding tokens if multiple organization data is requested
  • scheme - card scheme, one of "MASTERCARD / MAESTRO / VISA / OTHER"

Searching Tickets From the Ticketing System​

In the card tokenization result TPS provides two different tokens: epanToken & fundingToken.

  • epanToken is the token of the PAN number that was actually entered into the tokenization form.
  • fundingToken is either a PAN token of the funding card or a PAR token. It has the same value for all related cards.

After a customer has entered the PAN number to the tokenization form then the Ticketing System will search for tickets to display based on the card tokenization result data. Customers need to see tickets related to all of the linked cards (including cards in mobile devices) because it is often not possible to get the virtual card PAN to search tickets separately. In order to get all linked card tickets the Ticketing System has to search them using the fundingToken value (fundingToken has to be saved to the card instance on the Ticketing System side).

Strong Customer Authentication​

To implement strong customer authentication, it is possible to activate 3D Secure, which conducts authentication within the Sfey iFrame. Consequently, customers must authenticate themselves before accessing their travel history. For more information, please reach out to Sfey.