E-Commerce V2 Form Specification

Introduction

This E-Commerce app contains forms and messaging logic for processing PAN token generation.

These forms are hosted by us but are available for integration via iframe embedding. Each form can be controlled by parameters sent to the iframe.

The E-Commerce forms are able to communicate with the Transit Payment System (TPS), which is our backend, for processing the tokenisation.

The forms require an HMAC from the "parent", since HMAC calculation is done with a shared secret key, which needs to be kept secret.

We also host these pages for testing and integration purposes at separate DEV and TEST environments.

https://ecomm.test.sfey.com (more stable)
https://ecomm.dev.sfey.com (less stable)

These environments include a ps_mock component with them, which is an example parent page. It can be found at baseUrl/ps_mock/index.html

Both environments allow embedding from localhost.

The testing pages include static assets that can be helpful for integration.

The structure of the static assets folders:

root/
├─ ps_mock/
│  ├─ index.html
│  ├─ sha256.js
│  ├─ styles.css
├─ html/
│  ├─ token-generation-template.html.txt
├─ assets/
│  ├─ skins/
│  │  ├─ default.css

ps_mock/index.html -> This is not transpiled, meaning it can be easily downloaded and locally edited. This can also be opened locally as a plain .html file, embedding the DEV or TEST inside the iframe.
html/token-generation-template.html.txt -> Accurate representation of what the token-generation form might look like. The custom styling can be developed against this file. More about custom styles later on in the doc.
assets/skins/default.css -> Default skin. This can be downloaded and modified.

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.

The live environment does not include a ps_mock component.

Live environment: https://ecomm.sfey.com/

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)

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, the "parent" page should create an E-Commerce form by setting the iframe element src attribute to the E-commerce form URL.

Form initialization

The form should now start initialisation of the E-commerce app 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:

{
    form: "pan-token-generation",
    lang: "en",
    stylesheetName: "default",
    panFormatting: "enabled",
    transactionId: 1234567890,
    companyId: "23300001",
    additionalCompanyIds: ["23300002", "23300004"],
    useShortCardTokenForm: false,
    use3DSCardTokenForm: false,
    useExpressCheckout: false,
    placeholders: false,
    permissiveSubmitButton: false,
    datetime: "2017-07-03T10:28:44.073",
    appleButtonstyle: "black",
    googleButtonstyle: "black",
    hmacFields: ["transactionId", "companyId", "datetime", "hmacFields"],
    hmac: "150L5Vp9MNVzCSzwrp2RNIBkpirxt9/utTkGbD17ZP4="
}

Field descriptions:

Field	Description	Values	Default
form	Form to use.	`"pan-token-generation"` `"pan-token-generation-prn"`	mandatory
lang	Form language.	`"de"`, `"en"`, `"et"`, `"fi"`, `"lt"`, `"no"`, `"ru"`, `"sv"`, `"it"`	mandatory
stylesheetName	Form design. No template is applied automatically.	string	mandatory
panFormatting	Enables PAN field formatting with spaces.	`"disabled"` `"enabled"`	`"disabled"`
transactionId	Unique transaction id for this company. Used to link this form to the PAN token received from TPS.	int64 / uuid	mandatory
companyId	Company ID registered in TPS.	string	mandatory
additionalCompanyIds	When provided, the form will also return PAN tokens for these additional companies.	string[]	—
useShortCardTokenForm	When enabled, only the PAN field is shown. Overrides `use3DSCardTokenForm` — when both are enabled, only the PAN field is shown.	`true`, `false`	`true`
use3DSCardTokenForm	When enabled, adds a "Name on Card" field for 3DS authentication. Allowed characters: letters (including Unicode/diacritics), spaces, apostrophes, hyphens, periods, and commas. All other characters are silently removed.	`true`, `false`	`false`
useExpressCheckout	When enabled, shows Apple Pay and Google Pay buttons (if supported by the device and browser).	`true`, `false`	`false`
placeholders	When enabled, form inputs display placeholder examples (e.g. `1234 5678 9123 4567` for PAN, `09` / `28` for expiry, `John Doe` for name).	`true`, `false`	`true`
permissiveSubmitButton	When enabled, the submit button is only disabled during active processing. When disabled, the submit button is also disabled when the form has validation errors.	`true`, `false`	`true`
datetime	Transaction date and time in ISO 8601 format without timezone (`yyyy-MM-ddTHH:mm:ss.SSS`).	string	mandatory
appleButtonstyle	Apple Pay button style.	`"black"` `"white"` `"white-outline"`	`"black"`
googleButtonstyle	Google Pay button style.	`"black"` `"white"`	`"black"`
hmacFields	Fields used for HMAC calculation.	string[]	mandatory
hmac	Calculated HMAC value.	string	mandatory

Form param	Form name	Description
pan-token-generation	Generate PAN token	Tokenization with PAN
pan-token-generation-prn	Generate PAN token with statement reference	Tokenization with PAN or PRN (Payment Reference Number/Statement Reference)

Form Response

On a successful tokenization, the iFrame will send the parent a message (step 16) as such:

{
    "responseCodeName": "APPROVED",
    "responseCodeDescription": "Transaction finished successfully"
}

Form Customization

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

The html template to design the stylesheet against can be found here:
https://ecomm.test.sfey.com/html/token-generation-template.html.txt

The default stylesheet can be found here:
https://ecomm.test.sfey.com/assets/skins/default.css

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

If you need a new design template, please provide us the .css file you have created against the token-generation-template.html file. We will add it to the project making it available in all environments.

Apple Pay

Apple has strict guidelines for stylizing their buttons.
https://developer.apple.com/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons

Most of it is out of our control. What can be changed is:

Width, height, corner radius, padding
Style (black, white, white-outline)

To change the properties, you add this to the .css file:

/* example from our default style */
apple-pay-button {
  --apple-pay-button-width: 100%;
  --apple-pay-button-height: 45px;
  --apple-pay-button-border-radius: 4px;
  --apple-pay-button-padding: 0;
}

To change the Apple predefined style, you use the initialization field appleButtonstyle, which takes in black, white, or white-outline. Defaults to black.

Google Pay

Google Pay button style can be set via the initialization field googleButtonstyle, which accepts "black" or "white". Defaults to "black".

Google Pay button visibility is controlled by the useExpressCheckout initialization field. The button will only appear if the device and browser support Google Pay.

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.

Method	Resource
PUT	URL 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 linked 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.

Introduction​

Processing flow​

Messaging specification​

Form creation​

Form initialization​

Form Response​

Form Customization​

Apple Pay​

Google Pay​

Card Tokenization Result​

Searching Tickets From the Ticketing System​

Strong Customer Authentication​