User Interaction - Fidesmo

HOME OUR SOLUTION ABOUT US THE LATEST FIDESMO PAY LEARN MORE
ENGLISH
User interaction
framework for
delivery
The /userInteraction framework for delivery allows the Service Provider to:
1. Request additional information from the user once the service delivery process
has started with fields.
2. Push an action to be performed by the user’s device with action.
For a complete look at the architecture and the order of operations have a look at our Architecture pages.
/userInteraction is an API operation like any other available in the Fidesmo API, for example /ccm/install. The difference is that instead of interacting with the card, the SP gets to
interact with the user.
The general flow of service delivery with /userInteraction and field (the flow is the same for action) can be seen in the image to the right.
Help
ENGLISH
ENGLISH
ENGLISH
T
HOME
ENGLISH
OUR SOLUTION ABOUT US THE LATEST FIDESMO PAY LEARN MORE
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
a
HOME
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
a
HOME
ENGLISH
ENGLISH
ENGLISH
Dictionary – A map of strings the key represents language ID and the value is the translated text. en should be used as fallback and is mandatory to be supplied.
ENGLISH
ENGLISH
ENGLISH
A
HOME
ENGLISH
ENGLISH
ENGLISH
As described in the API documentation under the title Service Delivery requests, as soon as the Service Provider receives the service delivery request from the client, it will be able to
request specific data from the user or make the client do an action, in other words, do a user interaction. To do that, the Service Provider just needs to POST a JSON formatted
request to the /userInteraction endpoint that is either a field or action.
Field
The information that is requested from the user is presented in a form to which many fields can be added. Each field defined in the request has a direct correspondence with a system
UI component that will be rendered in the form shown to the user. For a better user experience grouping of related fields is a good idea although generally the forms should be kept as
short as possible. Once a user is done with a form they submit it with the submit button. This means that if a field depends on input from another field they need to be in separate
forms.
If the Service Providers service requires some information from the user before starting service delivery, we recommend to use the Service Description mechanism rather than field, as
it has been designed to be used in the setup phase.
A user interaction request is composed by an array fields. Each element of fields is described in the following table:
NAME DESCRIPTION TYPE
label The text label that will appear together with the system UI component defined by the type field. Multilanguage is supported. Dictionary
id The id used to identify this field String
type The type of UI control that the user will see in the Fidesmo App String
forma Provides an extra information about how the UI control will be rendered or what kind of data it will support. The format is optional and if not supplied or an unknown String
t format is used the field falls back to the default.
Fields inside a request
And finally, this is the list of type and format supported:
NAME TYPE FORMAT DESCRIPTION LABEL RETURNS
Date field date – Shows a date input to the user The text that should be shown A date as a string formatted as YYYY-MM-DD.
above the date input supplied as a
Dictionary.
Input text edit text Shows a text input. Default if format is not specified The label that should be shown The user input as a string or an empty string if nothing has
field or not supported. above the text input supplied as a been entered.
Dictionary.
number Text input, accepting numbers only The label that should be shown The numeric user input as a string or an empty string if
above the number input supplied as nothing has been entered.
a Dictionary.
obfuscate Numeric input for sensitive data. Should only The label that should be shown The user input as a string or an empty string if nothing has
d-number accept numbers and obfuscate them by default above the number input supplied as been entered.
unless the user toggles them to be shown. Should a Dictionary.
not use system keyboard, dictionaries or auto-
correct features.
password Text input for entering a password. Should not use The label that should be shown The user input as a string or an empty string if nothing has
dictionaries or auto-correct features. May be above the password input supplied been entered.
obfuscated. Platform specific best practices for as a Dictionary.
entering password data into a UI component are
expected to be followed.
email Text input for entering an email. The label that should be shown The user input as a string or an empty string if nothing has
above the email input supplied as a been entered.
Dictionary.
Markdown text – Shows a static text to the user. The text that should be shown, –
text field supplied as a Dictionary. The text
may contain basic markdown
elements like bold, emphasis or
links.
Check box check – Shows a checkbox with text to the user The label that should be shown Either the string “true” or “false”.
field box with the checkbox supplied as a
Dictionary.
Option field optio button A button or a set of buttons. If a button is pressed The labels, divided by \n, to be The numeric, zero-based position of the picked button in
n by the user the form is submitted. Having buttons in shown on the buttons supplied as a the provided array as a string.
the form automatically hides the submit-button. Dictionary.
Default if format is not specified or not supported.
radio Set of radio buttons for each line of a label. Dictionary where the key represents The numeric, zero-based position of the picked
language ID and the value is the radiobutton in the provided array as a string.
labels, divided by \n, to be shown
next to the radiobuttons.
NAME TYPE FORMAT DESCRIPTION LABEL RETURNS
Payment payme – The ENGLISH

label shown next to the input field supplied as a Payment card information as A PAN validated with the Luhn algorithm. The “cvv” field
card field ntcar Dictionary. number, expiration date and CVV might be optional depending on Service Provider
d code Configuration, then it can be left empty. JSONObject: {
"cardNumber": "XXXXXXXXXXXXXXXX", "expiryMonth": Int,
"expiryYear", Int, "cvv", "XXX" }
Supported data type and format

ENGLISH
ENGLISH
ENGLISH
D
HOME
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
v
HOME
ENGLISH
ENGLISH
ENGLISH
The application that the user is using is expected to validate the context to at least match the expected return format and size as per the above table.
ENGLISH
ENGLISH
ENGLISH
A
HOME
ENGLISH
ENGLISH
ENGLISH
The Service Provider should POST a JSON formatted request to the /userInteraction endpoint similar to the following structure:
{
"fields": [{
"label": {
"en": "English label",
"se": "Swedish label"
},
"id": "any_field_id",
"type": "edit",
"format": "number"
...
}],
"encrypted": "false"
}
ENGLISH
ENGLISH
ENGLISH
R
HOME
ENGLISH
ENGLISH
ENGLISH
The userInteraction request will yield an operationId and UUID. After some time (the user is filling in the required information) the Service Provider will receive the ID of the operation,
a status code and the results. The result will be in JSON and formatted like for example:
{
"operationId": "0276F6A6-E21C-4307-B63C-1F70D6C36045",
"sessionId": "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
"statusCode": 200,
"fields": {
"any_field_id": "field_string_value"
}
}
ENGLISH
ENGLISH
ENGLISH
E
HOME
ENGLISH
ENGLISH
ENGLISH
It is possible to specify that the data submitted by the user travels encrypted from the mobile client to the Service Provider, so that sensitive data such as payment card details
cannot be compromised.
Encrypted user interactions are done with a combination of symmetric and asymmetric encryption. An ephemeral AES key is generated by the client and used to encrypt
the /userInteraction data. Then, this key is encrypted with the public key of the Service Provider. The client returns the ephemeral-key encrypted data, and the public-key encrypted
ephemeral key. Upon receival, the Service Provider decrypts the ephemeral key with its private key, and then, with the newly decrypted ephemeral key, decrypts all the data.
To activate encryption the Service Provider needs to pass a public key as a certificate along with the service description:
{
"title": "The encrypted userInteraction service",
"description": "This is an encrypted userInteraction service.
Keep out of reach from children.",
...
"certificate": [A X.509 certificate encoded as ASN1.DER]
}
To encrypt a /userInteraction the Service Provider must also set the encrypted flag to true like for example:
{
"fields": [{
"label": {
"en": "English label"
},
"id": "any_field_id",
"type": "edit",
"format": "number",
...
}],
"encrypted": "true"
}
The encrypted data together with the encrypted ephemeral key will be sent back as previously described in the Result section but with the fields being encrypted and the additional
field "ephemeralKey":
{
"operationId" : "0276F6A6-E21C-4307-B63C-1F70D6C36045",
"sessionId" : "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
"statusCode": 200,
"fields": {
"any_field_id": [byte array in a hex form]
},
"ephemeralKey": [byte array in a hex form]
}
The "ephemeralKey" is encrypted using RSA/OAEP algorithm with a SHA512 for hashing and MGF1 Padding (RSA/NONE/OAEPWithSHA512AndMGF1Padding). To obtain field data one needs to
decrypt the "ephemeralKey" first and then using the obtained key to decrypt each field separately using AES/CBC algorithm with a PKCS7 padding (AES/CBC/PKCS7Padding). As
initialization vector an array with 16 zero bytes can be used.
ENGLISH
ENGLISH
ENGLISH
ENGLISH
E
HOME
ENGLISH
ENGLISH
ENGLISH
Show the user a policy text plus a checkbox for accepting the very same.
{
"fields": [
{
"label": {
"en": "Generic Brands collects information to provide a
better service to our users. The information we collect might
include your name, telephone number and credit card."
},
"id": "my_text_field_id",
"type": "edit",
"format": "text"
},
{
"label": {
"en": "I accept terms and conditions"
},
"id": "my_text_checkbox_id",
"type": "checkbox"
}
],
"encrypted" : "false"
}
Returned when user checks box and presses submit:
{
"operationId" : "MOCK",
"sessionId" : "MOCK",
"statusCode": 200,
"fields": {
"my_text_field_id": "",
"my_text_checkbox_id": "true"
}
}
Action
By sending list of action to the client the Service Provider can make the client perform a sequence of actions or a single action, for example make a call. The structure of
the action object is described in the following table:
NAME TYPE DESCRIPTION
description Translations The description/label that might appear in the UI if it is deemed necessary by the client. Supplied as a Dictionary.
name String The id used to identify this field.
parameters Map<string, string=""></string,> Any parameters that are necessary for the completion of the action.
action
When the client receives an action it will complete it to the best of it’s ability, however, sometimes the client is unable to complete the action. For example a UI client running on the
user’s phone will have no problem calling a phone number, however, a tablet UI client might not be able to do the same if it can’t do calling. In this case the tablet UI client will
instead show the user the description text as well as any passed parameters, so that the user can compete the action on another device.
ENGLISH
ENGLISH
ENGLISH
N
HOME
ENGLISH
ENGLISH
ENGLISH
NAME DESCRIPTION PARAMETERS
phonenu Calls or dials the specified phone number – Mandatory number that the client should call
mber number on the user’s device. If calling or or dial.
is not supported on the device the
provided description is shown to the
user together with the phone number
provided as parameter.
open- Opens the specified app on the user’s package – A mandatory String containing the app qualified-app-name – An intent-data-uri – An extra-text-value – An
android Android device automatically. package in order to create an explicit intent. If optional String containing a optional String optional String to be
-app the qualified-app-name and intent-data-uri parameters fully qualified app name containing a url sent with the Android
are not set the package is used to find a launch Intent in including the package in corresponding to an intent as payload with
the operating system. If no matching app is installed order to create an explicit app. the
the package will be used for searching on any available intent on Android. key android.intent.ext
app stores so that the user can install it. ra.TEXT.
Supported data type and format

ENGLISH
ENGLISH
ENGLISH
A
HOME
ENGLISH
ENGLISH
ENGLISH
The Service Provider should POST a JSON formatted request to the /userInteraction endpoint similar to the following structure:
{
"actions": [{
"description": {
"en": "English description",
"se": "Swedish description"
},
"name": "any_action_name",
"parameters": {
"parameter-name-1": "parameter_value",
"parameter-name-2": "parameter_value"
}
}],
"encrypted": "false"
}
ENGLISH
ENGLISH
ENGLISH
C
HOME
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
e
HOME
ENGLISH
ENGLISH
ENGLISH
{
"actions": [{
"description": {
"en": "Call this number +46XXXXXXXXX"
},
"name": "phonecall",
"parameters": {
"number": "+46XXXXXXXXX"
}
}]
}
The result would be that the UI client calls the number +46XXXXXXXXX.
ENGLISH
ENGLISH
ENGLISH
A
HOME
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
a
HOME
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
e
HOME
ENGLISH
ENGLISH
ENGLISH
{
"actions": [{
"description": {
"en": "Open XYZ app"
},
"name": "open-android-app",
"parameters": {
"package": "com.example.xyz",
"qualified-app-name": "com.example.xyz.XyzApp",
"extra-text-value": "example1234"
}
}]
}
The result would be that the UI client opens the XyzApp with the extra-text-value attached if the app is installed. Otherwise the UI client would search any available app stores
for com.example.xyz and ask the user to install the app.
ENGLISH
Ready to
get
started?
ENGLISH
ENGLISH
ENGLISH
G
C
HOME
ENGLISH
ENGLISH
ENGLISH
Fidesmo Pay
Our solution
The latest
Technology
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
ENGLISH
LinkedIn
Twitter
© 2022 Fidesmo Privacy policy

User Interaction - Fidesmo

Uploaded by

Copyright:

Available Formats

User Interaction - Fidesmo

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

User Interaction - Fidesmo

Uploaded by

Copyright:

Available Formats

HOME OUR SOLUTION ABOUT US THE LATEST FIDESMO PAY LEARN MORE

NAME DESCRIPTION TYPE

id The id used to identify this field String

Fields inside a request

And finally, this is the list of type and format supported:

NAME TYPE FORMAT DESCRIPTION LABEL RETURNS

Payment payme – The ENGLISH

Supported data type and format

Returned when user checks box and presses submit:

NAME TYPE DESCRIPTION

name String The id used to identify this field.

NAME DESCRIPTION PARAMETERS

Supported data type and format

© 2022 Fidesmo Privacy policy

You might also like