D201.5 Prototypes for Architecture, Security, Payment ... · OpenAM API) ... and specialized knowledge required to find, integrate, secure, monetize, and sustain innovative new applications

Ecosystem infrastructure for smart and personalised inclusion and PROSPERITY for ALL stakeholders

D201.5 Prototypes for Architecture, Security, Payment Infrastructure &

DeveloperSpace

Project Acronym Prosperity4All Grant Agreement number FP7-610510

Deliverable number D201.5 Work package number WP201

Work package title System Architecture and Unified-Listing/Marketplace

Authors Colin Clark, Gianna Tsakou, Gregg Vanderheiden

Status Final

Dissemination Level Public Delivery Date 26.02.2018

Number of Pages 70 plus 30 pages of Annex

Ecosystem infrastructure for smart and personalised inclusion and PROSPERITY for ALL stakeholders www.prosperity4all.eu

2

Version History

Revision Date Author Organisation Description

1 Dec. 19, 2017

Gianna Tsakou SILO Security, IAM, payment/micropayment, and crowd-funding infrastructures sections.

2 Dec. 19, 2017

Colin Clark, Simon Bates, Avtar Gill

IDRC Executive summary, contribution to overall architecture, Quality Infrastructure, and Nexus sections.

3 Jan 5, 2018 Gianna Tsakou Silo Revisions

4 Jan 20, 2018

Gregg Vanderheiden

RtF-I DeveloperSpace role and structure

5 Feb 20, 2018

Gregg Vanderheiden

RtF-I Revisions and synchronization

6 Feb 25, 2018

Gregg Vanderheiden

RtF-I Incorporating Review Feedback

http://www.prosperity4all.eu/


3

Table of Contents

1 Executive Summary ................................................................................................ 10

2 Contribution to the Global Architecture ................................................................. 11

3 Security-IAM and Payment Infrastructure .............................................................. 12

3.1 Introduction ............................................................................................................... 12

3.2 Security-IAM Infrastructure ....................................................................................... 12

3.2.1 Actors ................................................................................................................... 12

3.2.2 High-level Architecture ........................................................................................ 13

3.2.3 Functionalities ...................................................................................................... 15

3.2.3.1 User registration ........................................................................................... 15

3.2.3.2 Profile management ..................................................................................... 16

3.2.3.3 Application registration in IAM .................................................................... 18

3.2.3.4 Integration among registered application and IAM ..................................... 21

3.2.3.5 Access an integrated application from end-user perspective ..................... 22

3.2.4 Integrated P4A applications with the IAM infrastructure.................................... 26

3.2.5 Implementation .................................................................................................... 26

3.2.6 Installation guide .................................................................................................. 28

3.3 Payment Infrastructure ............................................................................................. 28

3.3.1 Actors ................................................................................................................... 29

3.3.2 High-level architecture ......................................................................................... 29

3.3.3 Functionalities ...................................................................................................... 31

3.3.4 Integrations .......................................................................................................... 32

3.3.5 Implementation .................................................................................................... 32

3.3.6 Installation guide .................................................................................................. 33

4 Crowd-funding architecture .................................................................................... 34

4.1 Positioning of the crowd funding subsystem ............................................................ 34

4.2 Functional Requirements & Specifications ................................................................ 35

4.3 Use Cases ................................................................................................................... 37

4.4 High Level Architecture ............................................................................................. 45



4

4.5 Selection of Technological Basis ................................................................................ 45

4.6 Implementation ......................................................................................................... 47

4.6.1 Requirements for the Application tier ................................................................. 47

4.6.2 Requirements for the Presentation tier ............................................................... 48

5 DeveloperSpace...................................................................................................... 51

5.1 The Big Picture ........................................................................................................... 51

5.2 Developers creating a new assistive technology. ...................................................... 52

5.3 Customers providing feedback to manufacturers. .................................................... 55

5.4 Companies looking for testers for their developments. ........................................... 57

5.5 Manufacturers wanting to market their products. ................................................... 58

6 Quality Infrastructure ............................................................................................. 59

6.1 Status of the Quality Infrastructure Implementation ............................................... 60

6.2 Future Work ............................................................................................................... 62

7 The Nexus ............................................................................................................... 63

7.1 The Co-Occurrence Engine ........................................................................................ 63

7.2 The Visible Nexus ....................................................................................................... 65

7.3 Status of the Nexus Implementation ......................................................................... 67

7.4 Future Work ............................................................................................................... 69

8 Conclusion .............................................................................................................. 70

9 Annex I ................................................................................................................... 71

9.1 Security APIs .............................................................................................................. 71

9.2 Payment APIs ............................................................................................................. 77

9.2.1 Authorize P4A application through Paypal REST API ........................................... 78

9.2.2 Establish a notification listener in Payment API (webhook) ................................ 78

9.2.3 Create and execute a payment through Payment API ......................................... 82

9.2.4 Create and execute a reccuring payment through Payment API ......................... 89

9.3 Register your app in Paypal ....................................................................................... 98



5

List of Tables

Table 1: Web service that provides the access token upon request (part of OpenAM API) ... 71

Table 2: Web service that provides the basic end-user profile upon request (part of OpenAM API) ............................................................................................................................. 72

Table 3: Web service that provides the extended end-user profile upon request (part of IAM API) ............................................................................................................................. 73

Table 4: Web service that provides end-user roles per application upon request (part of IAM API) ............................................................................................................................. 74

Table 5: Web service that validates an existing access token (part of OpenAM API) ............. 75

Table 6: Web service that refreshes an invalid access token using the refresh token (part of OpenAM API) .............................................................................................................. 76

Table 7: Useful endpoints of Paypal REST API .......................................................................... 77

Table 8: Useful endpoints of Payment API ............................................................................... 77

Table 9: Generate an access token in Paypal ........................................................................... 78

Table 10: Setup a webhook for your application ..................................................................... 78

Table 11: P4A application creates a payment on demand ...................................................... 82

Table 12: P4A application executes an approved payment ..................................................... 85

Table 13: P4A Application creates a billing plan on behalf of the service provider ................ 89

Table 14: P4A Application activates an existing billing plan on behalf of the service provider .................................................................................................................................... 92

Table 15: Create a billing agreement for recurring payment among service provider and consumer .................................................................................................................... 92

Table 16: Activate the billing agreement related to a recurring payment after consumer‘s approval ..................................................................................................................... 94



6

List of Figures

Figure 1: Overall Picture of Prosperity4all ............................................................................... 11

Figure 2: High level architecture .............................................................................................. 13

Figure 3 Typical Oauth2.0 flow................................................................................................. 14

Figure 4: OpenAM web-based console .................................................................................... 14

Figure 5: Required fields for completion of user‘s registration process .................................. 16

Figure 6: Profile overview ........................................................................................................ 17

Figure 7: Edit profile ................................................................................................................. 18

Figure 8: Change password ...................................................................................................... 18

Figure 9: Application owner registers his application in IAM .................................................. 19

Figure 10: Example of registered application in IAM (Assistance on Demand) ....................... 20

Figure 11: List of registered applications per application owner ............................................ 20

Figure 12: Manage the roles of the registered application ..................................................... 21

Figure 13: Sequence diagram depicts how an end-user accesses the protected resources of the Assistance on Demand platform through the IAM infrastructure ...................... 21

Figure 14: List of registered application in the IAM infrastructure ......................................... 23

Figure 15: End-user views his/her status (owner or member) per registered application .... 24

Figure 16: End-user confirms his/her membership of the Assistance on Demand platform .. 25

Figure 17: End-user selects the roles of interest in the Assistance on Demand platform ...... 25

Figure 18: Undo membership in the Assistance on Demand platform ................................... 26

Figure 19: The EER model that the IAM application uses. ....................................................... 27

Figure 20: High-level architecture of the Payment/micropayment infrastructure ................. 31

Figure 21: The EER model of the Payment API ........................................................................ 33

Figure 22: Crowd funding platform concept ............................................................................ 34

Figure 23: Interfaces with micro-payment ............................................................................... 35

Figure 24: Bidder User Case 1. A bidder gives money for a project with success ................... 38

Figure 25: Bidder User Case 2. A bidder makes a bid but the project is cancelled ................. 38

Figure 26: e Provider Use Case 1 .............................................................................................. 39

Figure 27: Service Provider Use Case 2. Project is cancelled ................................................... 40



7

Figure 28: Consumer Use Case. ................................................................................................ 41

Figure 29: Bidder Use Case Roles ............................................................................................. 42

Figure 30: Provider Use Case Roles .......................................................................................... 43

Figure 31: Consumer Main Roles ............................................................................................. 44

Figure 32: High Level architecture of the Crowd Funding subsystem ..................................... 45

Figure 33: Crowd funding Home page ..................................................................................... 49

Figure 34: Create a new Project Proposal ................................................................................ 50

Figure 35: User visits a projects page in order to support this project.................................... 50

Figure 36 Integration of the Unified Listing into the DeveloperSpace infrastructure ............. 51

Figure 37 Interaction between Stakeholders and the DeveloperSpace / Unified Listing ....... 52

Figure 38 Component directory and search option in the Unified Listing ............................... 53

Figure 39 The MasterList of Accessibility Strategies, one component in the LEARN section of the DeveloperSpace ................................................................................................... 53

Figure 40 The Unified Listing and the databases it is federated with ..................................... 54

Figure 41 Feedback features on each product page ................................................................ 55

Figure 42 Feedback/request feature on every search results listing ....................................... 55

Figure 43 Challenges page in the DeveloperSpace .................................................................. 55

Figure 44 Consumer “Tester” signup page in the DeveloperSpace ......................................... 57

Figure 45 Adding products page in the Unified Listing ............................................................ 58

Figure 46: Screenshot of the Quality Infrastructure Dashboard, showing graphs for the number of commits and contributors over time ....................................................... 62

Figure 47: A screenshot of the Visible Nexus application, showing a tree of components for the Inclusive Science Lab application. Model fields highlighted in yellow are ones that have recently changed as the result of incoming hardware sensor data. ......... 66

Figure 48: A mockup of the new user interface for the Visible Nexus, which improves the visual design and layout of the system. This design more clearly distinguishes between the component tree containment hierarchy (represented as solid, Bezier-curved lines) and ........................................................................................................ 67

Figure 49 The Nexus’ module and repository structure. ......................................................... 68

Figure 50: Consumer enters his Paypal credentials after redirection ..................................... 88

Figure 51: Consumer reviews the service in Paypal. ................................................................ 89



8

Figure 52: Consumer reviews the billing agreement of the desired service ........................... 97

Figure 53: Browse on your apps in the Paypal developer dashboard. .................................... 99

Figure 54: Register your application in Paypal ......................................................................... 99

Figure 55: Access the Sandbox API credentials of your application ........................................ 99



9

List of abbreviations

Abbreviation Full Form

IAM Identity & Access Manager

GUI Graphical User Interface

LDAP Lightweight Directory Access Protocol

API Application Programming Interface

MTV Model-Template-View

EER Enchanced Entity-Relationship

QI The P4A Quality Infrastructure



10

1 Executive Summary

The Prosperity4All technical architecture, which is the focal point of work package 201, provides a diverse collection of reusable services, applications, and APIs that support the creation of robust, secure, integrated, high-quality, and sustainable technologies—both within the DeveloperSpace infrastructure offered by the project, and by third-party developers who contribute to the larger Prosperity4all ecosystem.

This document describes the software prototypes that comprise the Prosperity4All architecture’s concrete implementation, including:

1. Security-IAM infrastructure 2. Payment infrastructure 3. Crowdfunding infrastructure 4. Quality Infrastructure (QI) 5. The Nexus integration APIs, Visible Nexus web interface, and Co-Occurrence Engine 6. DeveloperSpace web application

In each case, these prototypes were implemented, tested, deployed, and distributed in a form that provides developers with useful open source foundational tools that they can integrate into their own software projects. The goal of the prototypes is to lower the cost, complexity, and specialized knowledge required to find, integrate, secure, monetize, and sustain innovative new applications and assistive technologies.

Detailed architectural information about each these software prototypes—their goals, approach, and technical design—is described in D201.1, Specification of Architecture, Security, Payment Infrastructure, and DeveloperSpace. This document provides an overview of the software artefacts that have been implemented, where to find them, and how they can be used to support a sustainable ecosystem of tools, services, and strategies for prosperous inclusion.



11

2 Contribution to the Global Architecture

This document is part of WP201 System Architecture and Unified-Listing/Marketplace. The Unified Listing and OpenMarketplace are covered in a separate report D201.6. This document focuse on Prototypes for Architecture, Security, Payment Infrastructure & DeveloperSpace. As can be seen in Figure 1 these form the core infrastructure upon which the other components of Prosperity4All are built.

Figure 1 presents, in graphical form, the overall workpackages of the Prosperity4All and how the Security, Payment Infrastructure & DeveloperSpace infrastrutures provide the core for it all.

Figure 1: Overall Picture of Prosperity4all



12

3 Security-IAM and Payment Infrastructure

3.1 Introduction This chapter is the extension of the chapter 2 of D201-1. Chapter 2 of D201-1 defined the requirements and specifications of the security-IAM infrastructure and the Payment/micropayment infrastructure. The current chapter focuses on the final version of the aforementioned tools from the technical point of view, as implemented in the end of the project. In particular, we organize this chapter in the following sections:

• Security-IAM infrastructure: The final version of the infrastructure that has been implemented in the framework of the P4A project including the individual components,

• Payment/micropayment infrastructure: The final version of the infrastructure that has been implemented in the framework of the P4A project describing the individual components that it includes.

3.2 Security-IAM Infrastructure We are aligned with open source non-GPL IAM selection discussed in D201-1 by using the Forgerock OpenAM1. OpenAM is a powerful centralized access management solution, enabling companies to manage access control, federated services, single sign-on, and many other services while protecting their resources. OpenAM is part of the ForgeRock2 Identity Platform.

The Identity and Access Management infrastructure provides ready-to-use and easy-to-configure functionality related to user or service authentication and authorization. The IAM infrastructure can be integrated into existing web-based applications and services to provide typical services related to the identification of the user and the authentication of the user. All IAM – related actions can be logged. The IAM infrastructure comes with administration functionality for account and profile editing as well as editing the relationship and association among users.

3.2.1 Actors

The actors that we have identified in terms of the security-IAM infrastructure are the following:

• Resource/application owners • End-users • Administrator

The direct user of the Security-IAM infrastructure is the resource/application owner of any application/platform/service (e.g. Assistance on Demand platform – SP2) in the P4A ecosystem. This resource/application uses the Security_IAM infrastructure in order to protect the resources that it provides.

1 https://backstage.forgerock.com/docs/openam/12/release-notes/ 2 https://backstage.forgerock.com/



13

The users that want to access the protected resources of any (integrated with the Security-IAM infrastructure) application/platform/service can be considered as the end-users.

The administrator of the Security-IAM infrastructure is responsible for its maintenance and ensures the availability of the infrastructure. Also, the administrator is able to access and inspect the generated logs in order to address any reported issue.

3.2.2 High-level Architecture

The security-IAM infrastructure consists of two essential components: the ForgeRock OpenAM tool (version 12.0.0) and the IAM application that has been implemented by Singular Logic in the context of the P4A project on top of the OpenAM functionalities. Figure 2 presents the high level architecture of the infrastructure.

Figure 2: High level architecture

The OpenAM component is an open source access management, entitlements and federation server platform. The OpenAM component is written mainly in Java and its operation is based on the tomcat server. In this document, we focus only on the OpenAM functionalities that are required in terms of the P4A project. OpenAM supports features including the user authentication and authorization as well as the provision of logging. OpenAM supports user authentication through its OAuth2.0 authentication server. OAuth2.03 is an open standard for modern federation and authorization, allowing users to share their private resources with tokens instead of credentials.

Figure 3 depicts an abstract view of the OAuth2 flow. In our case, we typically use term resource to refer to any application. Furthermore the role of resource owner can be assigned to the administrator or the developer of the application.

3 https://tools.ietf.org/html/rfc6749



14

Figure 3 Typical Oauth2.0 flow

OpenAM supports full compliance with LDAP v3 by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. With regards to the logging, OpenAM tracks and keeps logs in a MySQL database for various types of activities including authentication, authorization and session logs. OpenAM also provides a web-based application including a GUI, called console, which the OpenAM administrator is able to access (see Figure 4). Through the OpenAM web-based console, the administrator is able to configure the OpenAM functionalities.

Figure 4: OpenAM web-based console

The OpenAM solution provides a set of RESTful and CREST web services (OpenAM API); part of them is used by the OpenAM component itself while other applications invoke them to exploit the functionalities of the OpenAM such as the authentication feature.



15

Singular Logic has implemented a web application, called IAM app, on top of the OpenAM solution. This application stores the information in a MySQL database (the encryption of sensitive data depends on the administrator; no passwords are stored there). This application supports the following functionalities through its dashboard:

• User registration and account management • Resource/application registration and management • Role registration and management per resource/application

Therefore, the users are able to create an account in the IAM infrastructure and manage their account through the GUI; the IAM app exploits the OpenAM specific web services in order to complete these actions. The protection of any application’s resources can be achieved through the IAM infrastructure. The IAM app offers the capability to the resource/application owners to protect the resources of their application by registering their application in the IAM infrastructure. The IAM app provides credentials per application by exploiting the OpenAM relative web services. The resource/application owner is able to declare the supported roles per application. As Figure 2 points out, the integration process between the IAM app and the OpenAM is achieved through the OpenAM API.

Singular Logic has also implemented the RESTful IAM API that extends the existing OpenAM API. The IAM API is used exclusively by the resource/application owners since it provides useful information about the end-users who access the protected resources of their (integrated with IAM infrastructure) applications. Further details are presented in the following sections.

The IAM landing page is accessible through the link http://83.235.169.221/prosperity4all/identity-access-manager/login/.

3.2.3 Functionalities

The below sections describe how any type of actor can create an account in the IAM app and his/her possibilities for profile management. Also, the registration process of a P4A application is described.

3.2.3.1 User registration

Any user is able to create a new account in the IAM infrastructure by clicking the “Join now” button in the IAM landing page or by following the link http://83.235.169.221/prosperity4all/identity-access-manager/signup-request/. There, the user has to type a valid email account that they own. When the resource/application owner submits the email account, an email notification will be sent to the defined email account including guidelines relevant to the registration process; the user has to follow the link “Signup now” enclosed in the email body to be registered.

Figure 5 depicts the fields that the registration page includes. We tried to make the registration page generic enough so as to cover the requirements of any application interested in integrating the IAM infrastructure, notably those in the P4All project that wanted to integrate with the IAM. The fields included in the profile support the related applications of P4all and have been agreed within the


http://83.235.169.221/prosperity4all/identity-access-manager/login/


http://83.235.169.221/prosperity4all/identity-access-manager/signup-request/

http://83.235.169.221/prosperity4all/identity-access-manager/signup-request/


16

consortium. To support all these features, Singular Logic has extended the basic profile functionality. Note that the fields marked with asterisk (*) are mandatory.

Figure 5: Required fields for completion of user‘s registration process

3.2.3.2 Profile management

Supposing that the user has completed the registration successfully, they are able to log in the IAM app providing his/her credentials. Upon successful user authentication, the user can access the overview of his/her profile through the top menu “Hi {username} > My account”. Figure 6 depicts what the profile looks like.



17

Figure 6: Profile overview

Any user is able to edit his/her profile (with the exception of the username) by clicking on “Edit” button as depicted in Figure 7. Any logged in user has the option to change his/her password as seen in Figure 8. The user has to enter the old password once and the new password twice. After the user submits the new password, he/she will be directed to the login page to enter the new credentials.

Any user is able to disable or even delete his/her account upon request towards to the administrator of the IAM infrastructure.



18

Figure 7: Edit profile

Figure 8: Change password

3.2.3.3 Application registration in IAM

All P4A applications (and more) can be protected using the IAM infrastructure. The owner of the resource/application needs to be registered in the IAM app. Upon successful authentication in the IAM app, the resource/application owner needs to register their application by providing the related details. The resource owner may access his/her applications’ dashboard through the “Applications > My applications” (top menu). There, the resource owner can register their application as a first step to integrate with the IAM.



19

Figure 9: Application owner registers his application in IAM

After the pressing of the button “Register an application”, the following fields should be filled in (see Figure 9):

• the name of the application, • the description of the application, • the base URL of the application, • the callback URL of the application that is required by the Oauth2.0 protocol, • the email account of the application owner

In meanwhile, the resource owner will be notified about the CLIENT_ID and the CLIENT_SECRET that characterizes uniquely the registered application in IAM (OpenAM authorization server); they constitute the credentials of the application, so the CLIENT_SECRET must be secret and protected. The CLIENT_ID and CLIENT_SECRET of each application are provided through the OpenAM API. Figure 10 depicts the details of the Assistance on Demand application4, one of the applications that have been registered in IAM. The resource owner can update the details of any registered application that they own by clicking on the “Edit” button.

4 http://83.235.169.221:8025/en/



20

Figure 10: Example of registered application in IAM (Assistance on Demand)

Figure 11: List of registered applications per application owner

The resource owner is able to define a set of user roles related to the application that they just registered. This process makes sense in case that the application allows for specific rights for different user roles. To manage the roles, the resource owner has to click on the “Roles” button (see Figure 11). In case that the desired role does not exist in the list, the resource owner in cooperation with the administrator is able to add a new one by clicking on “Add” button and providing the name and a brief description of the role (see Figure 12). Alternatively, the resource owner could contact the administrator of the IAM infastructure. depicts the roles that the Assistance on Demand application supports (e.g. carer, service_consumer, service_provider).



21

The IAM component shares with any registered application the roles of any authenticated end-user relevant to that application but will not implement any role-dependent policy at the application side; each indivindual application is responsible to adjust its content and behaviour by taking into account the roles of the end-user.

Figure 12: Manage the roles of the registered application

3.2.3.4 Integration among registered application and IAM

Figure 13 depicts the sequence diagram among the IAM infrastructure and a typical P4A application, for instance the Assistance on Demand platform, that is followed when an end-user requests access to the protected resources of the Assistance on Demand platform The user is redirected in the centralized IAM login page (action 2) where he/she enters the credentials and then, a set of actions are performed in the background including the generation of access token, the retrieval of users‘s basic or/and extended profile, the retrieval the user’s role in the application. After the background processes, the user is landed in the P4A application and is able to access the protected resources.

More details about the provided APIs that are used in actions 3-8 can be found in Annex I (section Security APIs).

Figure 13: Sequence diagram depicts how an end-user accesses the protected resources of the Assistance on Demand platform through the IAM infrastructure



22

3.2.3.5 Access an integrated application from end-user perspective

Any end-user is able to access the protected resources of any (integrated with the IAM) application as long as they have an active account in the IAM infrastructure. Upon successful authentication in the IAM app login page, the end-user is directed to the landing page of the IAM app where the list of the registered applications that may be accessed by the given user is depicted (see Figure 14).



23

Figure 14: List of registered application in the IAM infrastructure

The end-user can become a member of any application through the top menu on Applications > Available applications. lists the registered applications. The label owner in the right side of an application means that the user is also the resource/application owner. A resource owner can also be a member of this application without limitations. The label member states that the end-user is a member of the application.



24

Figure 15: End-user views his/her status (owner or member) per registered application

To become a member of an application, the end-user has to press on the Membership button and confirm the membership (see Figure 16). In the next step, the end-user must define his/her roles (if the application allows roles) in the applications he/she is a member of (see Figure 17). The end-user accesses a list of supported roles (usually different) per application providing a brief description and is able to select the role(s) of interest. The IAM infastructure shares with this application the roles of the end-user but each application is responsible to manage the related browsing of roles.

The aforementioned steps should be followed by the end-user once per application of interest.

The end-user is able to cancel his/her membership to an application as depicted in Figure 18.



25

Figure 16: End-user confirms his/her membership of the Assistance on Demand platform

Figure 17: End-user selects the roles of interest in the Assistance on Demand platform



26

Figure 18: Undo membership in the Assistance on Demand platform

3.2.4 Integrated P4A applications with the IAM infrastructure

The previous section described the steps that an application owner follows in order to protect the resources of an application through the IAM infrastructure. In the framework of the P4A, the IAM infrastructure has been integrated with the following applications:

• Assistance on Demand platform (SP2) • Social network as part of Assistance on Demand platform (SP2) • Crowd funding platform (SP2) • Payment/micropayment infrastructure (SP2) • Microlabora (SP2) • Print service (SP3) • Sociable (SP3)

3.2.5 Implementation

The implementation of the IAM application and the API has been performed through the Django framework5 and the Django Rest framework using Python6 2.7 as programming language. The IAM

5 https://www.djangoproject.com/



27

application was implemented using the MTV design pattern (variation of MVC design pattern). The term view constitutes the Business layer of the back-end architecture and describes which data are presented. This layer consists of the URLs and views modules. The former describes a set of IAM application’s URLs and the latter contains the business logic of the application. Each URL is associated with a method in views. The term template constitutes the Presentation layer of the architecture and describes how the data are presented. The acronym model, which depicts the Data layer, stores data in the MySQL database using the Django ORM (Object-relational mapping) that maps the data from the relational way to object structure and vice versa. The API that IAM exposes interacts with the MySQL database component and provides a set of REST web services to external applications. Figure 19 presents the EER model of the IAM application.

Figure 19: The EER model that the IAM application uses.

For the documentation of the implemented web services the Swagger framework7 has been used. The advantage of the Swagger is the fact that the documentation is online and up-to-date, since it takes into account any changes during the development process. The IDEs that the development

6 https://www.python.org/ 7 https://swagger.io/



28

team used during the development phase include the Visual Studio 2013 community edition8 and the PyCharm9. With regard to the version control system, git10 was used for tracking changes during the development phase of the software.

3.2.6 Installation guide

The installation of the IAM infrastructure prototype consists of the installation of the ForgeRock OpenAM solution and the installation of the IAM app. Although we have installed them in two discrete OpenStack11 Virtual machines (ubuntu 14.04), both of them could be installed either in a Virtual machine or a physical server.

The installation steps of the OpenAM are described with details at https://backstage.forgerock.com/docs/openam/12/install-guide/. During the installation process, it is proposed to use SSL in the application layer-HTTP (part of tomcat server configuration). Our prototype uses the OpenAM 12.0.0 Build 11961 (2014-December-17 21:16). The minimum hardware requirements are 4GB RAM, 2 CPU cores and 80 GB hard disk but it depends of the scale of the installation. OpenAM uses the ports 80, 8080, 8081, 53, 443, 639, 8000, 8085.

Regarding the IAM application that we have implemented in P4A, the source code and the installation process is available in the github https://github.com/silop4all/iam. This software is provided under Apache 2.012 license. The minimum hardware requirements are 2GB RAM, 1 CPU core and at least 40GB hard disk. The traffic in ports 80, 443 should be allowed.

The IAM prototype is publicly accessible through any browser by typing the link http://83.235.169.221/prosperity4all/identity-access-manager/login/.

3.3 Payment Infrastructure According to Task 201.3, a secure payment infrastructure for the P4A ecosystem should be designed and implemented. The functional requirements / specifications and the non-functional requirements of secure payment infrastructure have been described in the deliverable D201.1 (see section 2.4).

As noted already in the Description of Work and in D201.1, the focus of the payment system in P4A is not on building a novel payment infrastructure but on implementing applied technologies for adding payment functionality as a resource in the DeveloperSpace. The Payment infrastructure facilitates the service/product providers to integrate payment functionality in order to sell their services/products while, in parallel, it provides the capability to service/product consumers to purchase both machine and human offered resources (services, applications, AT, etc) using a uniform solution. The Payment infrastructure can be used by all platforms, services and components of the

8 https://www.visualstudio.com/en-us/news/releasenotes/vs2013-community-vs 9 https://www.jetbrains.com/pycharm/ 10 https://en.wikipedia.org/wiki/Git 11 https://www.openstack.org/ 12 https://www.apache.org/licenses/LICENSE-2.0


https://backstage.forgerock.com/docs/openam/12/install-guide/

https://github.com/silop4all/iam



29

P4A ecosystem (and beyond it) that need to support some kind of financial transaction. The payment infrastructure, as part of the DeveloperSpace resources that are available for integration can relieves service providers from a significant part of the effort required to develop (from scratch) a payment system or implement interaction with third-party systems.

3.3.1 Actors

The actors that we have identified in terms of the payment infrastructure are the following:

• Service / product provider • Service / product consumer • Administrator

The service / product provider (also called merchant) is the user that offers a service or product (in any application/service/platform that the P4A ecosystem includes or beyond it) including a fee.

The service / product consumer (also called customer) is the user that purchases a service or product through any P4A application/service/platform or beyond it.

The administrator is a special user that ensures the normal and expected operation of the payment/micropayment infrastructure.

3.3.2 High-level architecture

The payment/micropayment infrastructure consists of two essential components: the Paypal13 gateway and the Payment API that has been implemented by Singular Logic in the context of P4A project.

The Paypal solution has been selected as a well-known trusted electronic payment system to perform payment transactions. Further justifications and related state of the art review related to this choice can be found in D201.1. Paypal provides a set of APIs14 that exposes its overall functionalities for integration purposes and a web application that users can access. Of the PayPal-provided REST APIs and NVP/SOAP APIs, the REST APIs have used in order to meet the project requirements. Paypal REST APIs are HTTP-based RESTful APIs that use the OAuth 2.015 protocol for authorization.

Singular Logic has implemented the payment API. The payment API operates as a mediator among the P4A building blocks (platforms, services etc) and the Paypal solution. The payment API includes three types of web services: 1) web services related to the payment transactions, 2) web services related to the users reporting, and 3) web services that consume notifications coming directly from Paypal.

Any service (or product) provider is able to register and sell a service by defining the charging policy through a P4A application that uses the Payment infrastructure. To do this, the P4A application

13 https://www.paypal.com/gr/home 14 https://developer.paypal.com/docs/api/overview/ 15 https://oauth.net/2/



30

needs to be already integrated with the P4A IAM infrastructure, while the service provider needs to be authenticated and own a business account in Paypal associated with a registered Paypal app. The P4A application invokes specific web services included in the Payment API aiming to create a payment definition in the Paypal. The Payment API validates that the request is coming from a trusted (or not) application through the OpenAM API (IAM infrastructure). In case that the application is a trusted one, the Payment API forwards the request towards the Paypal REST API (since the Payment API acts as a wrapper of the Paypal REST API), the Paypal creates a payment definition for the specific service offered by the given service provider and returns the payment definition in the P4A application through the Payment API. In the meantime, the Payment API keeps a piece of information in a persistent database; specifically, it stores the service provider who sells the service with a given fee / charging policy and the P4A application that performs the request. The creation of the payment definition of a service is transparent for the service provider (all the functionalities are performed through web services through the given P4A application).

On the other hand, provided that the payment process definition has been created for a specific service (i.e. provided that a specific service is integrated with the P4A payment infrastructure), the service consumer is able to purchase this service through the P4A application that hosts it. When the consumer decides to purchase the service, the P4A application propagates this request to the Payment API which validates that the consumer is authenticated, the P4A application is trusted and the Paypal app of the provider is valid. The Payment API invokes specific web services included in the Paypal REST API. Afterwards, the browser of the service consumer is redirected to the Paypal GUI where the consumer is able to inspect the payment process definition (fee, taxes, charging policy e.t.c.) of the service, confirm his/her agreement with the payment process definition and purchase the service. The service consumer is able to purchase the service using either his/her personal account in Paypal or a credit card. It’s worth to stress here that the payment transaction is performed in the Paypal GUI. The service consumer is able to proceed to the purchase of the service or to skip it in the Paypal GUI. In both cases, the browser of service consumer is redirected to the P4A application.

The Payment API contains a specific web service that receives notifications coming directly from Paypal. These notifications are stored in the persistent database that the Payment API provides.

Paypal performs payment or micropayment operations based on the amount of service fee. The charging policy could be a one-off payment, payment per usage or subscription-driven payment such as payment per day, week or month. Figure 20 presents the high level architecture of the infrastructure.



31

Figure 20: High-level architecture of the Payment/micropayment infrastructure

The Payment/micropayment infrastructure can be used by any P4A application assuming the following:

• The P4A application owner has been registered in the IAM infrastructure and is considered as trusted.

• The service provider has been registered in the IAM infrastructure. • The service provider has created a business account in Paypal and has registered an

application in the Paypal dashboard (see section 9.1). That means that the service provider is able to access his Paypal account through his/her credentials and also, owns the credentials of his application in the Paypal.

• The P4A application that sells services or products is aware of the service provider Paypal application’s credentials.

• The service provider is able to log in the P4A application and register a service by defining its fee and the relevant charging policy.

• The service consumer has been registered in the IAM infrastructure and is able to log in the P4A application and purchase the service of interest.

3.3.3 Functionalities

In this section, we assume that the service providers and consumers are registered in the IAM infrastructure. Also, we assume that the service provider owns a business account in Paypal and has registered the P4A application as a Paypal application. Therefore, the P4A application is able to be identified through the Paypal credentials, the client_id and secret that will be mentioned as paypal_client_id and paypal_client_secret.

In terms of the functionalities, the payment/micropayment infrastructure provides the following:

• Support a variety of charging models. Any service or product can be charged per usage, one-off or per day/week/month (a kind of subscription) based on the service/product provider preferences



32

• Support payment. The service consumer is able to pay a service/product provider for a service/product that owns according to the value of this service/product.

• Support micropayment. The service consumer is able to make micropayments for a service/product according to the value of this service/product. The Paypal applies different policy (fees) in the service/product providers for low-value transactions (typically under €10 in value). The micropayment rate is available to all service/product providers and in all countries where business accounts are available.

• Provide notifications. The participants are notified when a transaction is held. • Provide reporting. Both service consumer and service provider are able to access reports

related to the payments either directly to the Paypal dashboard or through the integrated P4A applications (the payment/micropayment infrastructure exposes an interface that the integrated applications can retrieve useful information).

The transactions in the payment/micropayment infrastructure are secure since SSL over HTTP protocol is used. More details about the provided APIs can be found in Annex I (section Payment APIs).

3.3.4 Integrations

In the framework of the P4A project, the Payment/micropayment infrastructure has been integrated with the following applications:

• Assistance on Demand platform (SP2) • IAM infrastructure (SP2) • Crowd funding platform (SP2) • Microlabora (SP2) • Print service (SP3)

• OpenMarketplace

3.3.5 Implementation

The implementation of the Payment API has been performed through the Django Rest framework written in Python16 2. The Payment API interacts with a relational database and provides a set of REST web services to external applications upon request. The database that is used is a MySQL database and the EER model of the component is depicted in Figure 21.

The IDEs that the development team used during the development phase include the Visual Studio 2013 community edition17. With regard to the version control system, git has been used for tracking changes during the development phase of the software.

16 https://www.python.org/ 17 https://www.visualstudio.com/en-us/news/releasenotes/vs2013-community-vs



33

Figure 21: The EER model of the Payment API

3.3.6 Installation guide

The source code and the installation process of the Payment API is available at the link https://github.com/silop4all/payment-api. It is required to deploy it using HTTPS (SSL over HTTP). This software is provided under Apache 2.018 license. The minimum hardware requirements are 2GB RAM, 2 CPU core and at least 40GB hard disk. The traffic in ports 80, 443 should be allowed.

The prototype of the Payment REST API is publicly accessible through any browser by typing the link https://83.235.169.221:443/docs/.

18 https://www.apache.org/licenses/LICENSE-2.0


https://github.com/silop4all/payment-api

https://83.235.169.221/docs/


34

4 Crowd-funding architecture

4.1 Positioning of the crowd funding subsystem

The crowd-funding platform was explored as a means of financing desired accessibility features.

Crowd-funding would be a collective effort by consumers who network and pool their money

together, usually online, in order to invest in and support efforts initiated by other people or

organizations. The basic idea of crowd funding was for an entrepreneur to raise external finance

from a large audience, where each individual provides a very small amount, instead of soliciting a

small group of sophisticated investors. The users (i.e. developers, service providers, etc.) who get

funds would be solely responsible for fulfilling the promises made in relation to their service or

product. If they were unable to satisfy the terms of the agreement, they may be subject to legal

action by backers/bidders. Usually, a user agreement is defined and informs users and consumers

about their obligations and rights.

Figure 22: Crowd funding platform concept

In the P4All project, the crowd funding subsystem was meant to enable users (consumers or

developers or resource owners) or a third party to outline a desired accessibility product or feature

or service and aggregate bids for its creation. Then, resource (e.g. AT product) owners, developers or

service providers (depending on the bid) would be notified and prompted to declare whether they

intend to create the desired resource.

The interoperation of the crowd funding subsystem with other P4All components is shown in Figure

20 above.

The crowd funding subsystem can be used via the AoD, the open source developments can be found here: https://ds.gpii.net/develop/components/crowd-funding


https://ds.gpii.net/develop/components/crowd-funding


35

Figure 23: Interfaces with micro-payment

4.2 Functional Requirements & Specifications

Based on the above description, on state-of-the-art survey of other existing crowd funding systems

and relevant P4All project discussions and documents (e.g. SP1 deliverables), the main system

requirements and functional specifications of the P4All crowd funding subsystem are:

• The smooth and reliable support of fine-grained payments, leveraging on emerging micropayments technologies, which are fair and flexible enough to support the aggregation of bids for products or services. Thus, interoperability with the micro-payments subsystem is required.

• The support of interactivity, communication and collaborative capabilities among the resource owners (product developers or service providers) and the consumers.

• A mechanism for rewarding the backers/bidders. In the P4All case, most frequently the reward may be access of the bidders to the requested accessibility feature. Moreover, a notification mechanism will be used for enabling thank you message to the bidders.

From the perspective of consumers (bidders) using the crowd funding platform:

• Bidders should only be charged if the “project” (i.e. service or product development) reaches

its fundraising goal. They have to provide their payment information when they pledge, but

they will not be charged immediately. The payment will only be collected if, at the time of

the project’s funding deadline, the project has reached its fundraising goal. The exact

amount they pledged is the amount that will be collected. If the campaign has not reached

its fundraising goal, bidders should not be charged, no funds should be collected, and no

money should change hands.

• Bidders should be able to invite others to contribute through the crowd funding platform.



36

• Bidders should be able to change or cancel their pledge at any time before the project’s

funding deadline (with one exception). They can increase, decrease, or cancel their pledge at

any time during the campaign, with one exception. During the last 24 hours of the campaign,

they can’t decrease or cancel their pledge — if that action would drop the project below its

funding goal. Once the project has been funded, they can only cancel or change their pledge

by making special arrangements directly with the project/service provider.

• In case that there is a reward involved, bidders should be able to respond to product/service

providers to questions about the reward (e.g. mailing address for the reward, etc.) Such

information should be requested after the campaign has succeeded. To receive the reward,

everyone has to provide the information in a reasonable amount of time specified by the

service provider.

• Bidders should be able to request a specific service, or product feature or AT from the

developers’ community and ask for offers from developers/service providers. The person

who requests the service may define the minimum/maximum amount for the bid or may

choose to leave it open and wait to see how much money will be offered.

• Bidders should not be able to ask for refunds. Responsibility for finishing a project lies

entirely with the project/service provider. Prosperity4All doesn’t hold funds on

project/service provider’s behalf, cannot guarantee creators’ work, and does not offer

refunds.

• Will not have guarantee for the Estimated Delivery Date. The date listed on each

project/service provider may change as the project/service provider works on the project.

From the perspective of product/service developers that receive aggregated funds using the crowd

funding platform:

• They should have the ability to refund individual pledges if he wants. After the project has

been funded, they should be able to cancel and refund a backer’s pledge at any time. If they

do so, they should have no further obligation to that specific backer.

When a service/project fails (although adequate funds are available, the crowd funding platform

should ask the service provider to;

• Post an update that explains what work has been done, how funds were used, and what

prevents him from finishing the project as planned;



37

• Return any remaining funds to backers, or else explain how those funds will be used to

complete the project in some alternate form and time schedule.

4.3 Use Cases

Primary Actors:

System Integrator: Integrates the crowd funding subsystem in an existing platform will with his own

system. Within the P4All project, it is expected that the AoD infrastructure of WP205 will integrate

the crowd funding subsystem in order to enable bidding for new services desired by consumers.

Similar is the case of the Open market place of WP201.

Bidder: The bidder is the user that makes bids to projects.

Provider: The Provider is the product/service provider or developer who suggests projects that need

bidding, i.e. that will be implemented if adequate funding is raised.

Consumer: The Consumer is the user that makes a project proposal. If the project proposal is

selected by bidders and providers then it becomes a new project.

Main Scenario: Bidders use crowd funding to bring new services/products to market.

Providers use crowd funding to find resources in order to create new services-products.

Consumers use crowd funding to suggest new services/products that better meet their needs; other

consumers (potential bidders) may choose to contribute to the crowd funding of such products and

service/product developers may choose to provide an offer for implementation.

The following discussion specifies the relevant use cases to be implemented.



38

Figure 24: Bidder User Case 1. A bidder gives money for a project with success

The bidder logs into the crowd funding platform. He browses the projects that are available and he

places a bid to the project that attracts him most. If the projects meets all the requirements (total

amount of money, etc.) then the bidder has to pay the amount of his bid. After the project closes,

the amount is paid and the bidder receives the award (if applicable).

Figure 25: Bidder User Case 2. A bidder makes a bid but the project is cancelled



39

The bidder logs into the system. He browses the projects that are available and he places a bid to the

project that attracts him most. The projects does not meet all the requirements (total amount of

money, assignment to suitable developer, etc.) so the project is cancelled and the bidder will not pay

the amount of his bid.

Figure 26: e Provider Use Case 1

The Service Provider logs into the system. He creates a new project and he enters detailed

information about the project. If the project attracts bidders and meets all the requirements (total

amount of money in the specific period of time) then the Service provider reserves the money and he

starts the project implementation. When the project finishes the service provider delivers the

project/service and receives the money.



40

Figure 27: Service Provider Use Case 2. Project is cancelled

The Service Provider logs into the system. He creates a new project and he enters detailed

information about the project (description, budget, time schedule, etc.). The project does not attract

bidders and does not meet all the requirements (total amount of money in the specific period of

time) so the payments are cancelled and the project stops. The service provider is informed that the

project/service implementation was cancelled.



41

Figure 28: Consumer Use Case.

The Consumer logs into the system. He creates a new service/project proposal with all the required

details about the service/project. If the project attracts bidders and Providers accept to implement it

then the service/project starts. The Consumer can notify the selected Provider that he has been

assigned the project. When the project finishes the consumer can use the new project/service.



42

Figure 29: Bidder Use Case Roles

The Bidder can: • Browse Projects that are available for bidding • Share a Project to social media • Select a Project in order to bid money for it • Make a bid • Make a payment • Discuss with the Service Provider • Request the implementation of a service/Project



43

Figure 30: Provider Use Case Roles

The Service Provider can: • Browse Projects • Create a new Project with a specific budget and a specific time period for

implementation. • Reserve bids in order to implement a project (but is actually paid after the delivery of the

Project) • Implement a project (i.e. produce project results) • Request and Collect amount of money (payments) of the bidders • Give offers for projects proposed by consumers.



44

Figure 31: Consumer Main Roles

The Consumer can: • Register/Login to the system • Browse Projects • Create a new Project /Service proposal for implementation • Communicate with Providers to explain what the project requirements are • Close a budget for a service implementation • Assign the project to a Provider • Share a Project/Service



45

4.4 High Level Architecture

The crowd funding component will function inside the P4All ecosystem as a subsystem. In order to

maximize trust in relation to payments, we plan to integrate web APIs offered by well trusted and

widely used 3rd party components. The functionality will run through a common browser (no need for

extra infrastructure). To execute this functionality, crowd funding communicates with other P4A

systems, the Payment Infrastructure (Payments and micropayments), external entities (Social

Media), the Security Component, Chat facility and Notification facility.

Figure 32: High Level architecture of the Crowd Funding subsystem

4.5 Selection of Technological Basis

Taking into consideration the overall project requirements, the Crowd Funding would be a Java

custom made solution using:

- Spring Framework: is an application framework and inversion of control container for

the Java platform. it includes several modules that provide a range of useful services for both

micropayments and crowdfunding, like:

o Spring Core Container: This is the base module of Spring and provides spring

containers (BeanFactory and ApplicationContext).

o Aspect-oriented programming: enables implementing cross-cutting concerns.


https://en.wikipedia.org/wiki/Inversion_of_control

https://en.wikipedia.org/wiki/Servlet_container

https://en.wikipedia.org/wiki/Java_platform

https://en.wikipedia.org/wiki/Aspect-oriented_programming

https://en.wikipedia.org/wiki/Cross-cutting_concern


46

o Authentication and authorization: configurable security processes that support a

range of standards, protocols, tools and practices via the Spring Security sub-project

(formerly Acegi Security System for Spring).

o Convention over configuration: a rapid application development solution for Spring-

based enterprise applications is offered in the Spring Roo module.

o Data access: working with relational database management systems on the Java

platform using JDBC and object-relational mapping tools and with NoSQL databases.

o Inversion of control container: configuration of application components and lifecycle

management of Java objects, done mainly via dependency injection.

o Testing: support classes for writing unit tests and integration tests.

- Java Server Faces: is a java specification for building component – based user interfaces for

web applications. Based on a component-driven UI design-model, JavaServer Faces uses XML

files called view templates or Facelets views.

- Primefaces: PrimeFaces is a component suite open source User Interface (UI) component

library for JavaServer Faces (JSF) based applications.

- Hibernate: Hibernate ORM (Hibernate in short) is an object-relational

mapping framework for the Java language, providing a framework for mapping an object-

oriented domain model to a traditional relational database. Hibernate solves object-

relational impedance mismatch problems by replacing directpersistence-related database

accesses with high-level object handling functions.

- Symfony: Symfony is a set of reusable PHP component and a PHP framework for web

projects. Symfony was heavily inspired by the Spring Framework. Symfony makes heavy use

of existing PHP open-source projects as part of the framework, including:

o Doctrine as object-relational mapping layer o PDO database abstraction layer o PHPUnit, a unit testing framework o Twig, a templating engine o Swift Mailer, an e-mail library


https://en.wikipedia.org/wiki/Authentication

https://en.wikipedia.org/wiki/Authorization

https://en.wikipedia.org/wiki/Spring_Security

https://en.wikipedia.org/wiki/Convention_over_configuration

https://en.wikipedia.org/wiki/Spring_Roo

https://en.wikipedia.org/wiki/Data_access

https://en.wikipedia.org/wiki/RDBMS

https://en.wikipedia.org/wiki/JDBC

https://en.wikipedia.org/wiki/Object-relational_mapping

https://en.wikipedia.org/wiki/NoSQL

https://en.wikipedia.org/wiki/Inversion_of_control

https://en.wikipedia.org/wiki/Dependency_injection

https://en.wikipedia.org/wiki/User_interface

https://en.wikipedia.org/wiki/Facelets

https://en.wikipedia.org/wiki/Open_source

https://en.wikipedia.org/wiki/User_Interface

https://en.wikipedia.org/wiki/JavaServer_Faces



https://en.wikipedia.org/wiki/Software_framework

https://en.wikipedia.org/wiki/Java_(programming_language)

https://en.wikipedia.org/wiki/Software_framework

https://en.wikipedia.org/wiki/Object-oriented_programming

https://en.wikipedia.org/wiki/Object-oriented_programming

https://en.wikipedia.org/wiki/Domain_model

https://en.wikipedia.org/wiki/Relational_database

https://en.wikipedia.org/wiki/Object-relational_impedance_mismatch

https://en.wikipedia.org/wiki/Object-relational_impedance_mismatch

https://en.wikipedia.org/wiki/Persistence_(computer_science)


47

4.6 Implementation

The Crowd Funding component was implemented as a 3-tier application. Three-tier architecture is a

client–server software architecture pattern in which the user interface (presentation), functional

process logic ("business rules"), computer data storage and data access are developed and

maintained as independent modules. Apart from the usual advantages of modular software with

well-defined interfaces, the three-tier architecture is intended to allow any of the three tiers to be

upgraded or replaced independently in response to changes in requirements or technology. The 3

tiers are:

• The Presentation tier. A web application that uses the Symfony PHP framework.

• The Application tier (business logic). A Java web service providing a REST API.

• The Data tier. The DBMS (MySQL).

4.6.1 Requirements for the Application tier

The Application tier is a RESTful web-service that is responsible for receiving and transmitting

requests and responses from and to the presentation tier. It also acts as the intermediary to the

back-end database.

The Web Service REST APIs provide access to resources (data entities) via URI paths. To use a REST

API, the presentation tier will make an HTTP request and parse the response. The response format is

JSON. The HTTP methods are standard HTTP methods like GET, PUT, POST and DELETE.

This section describes the Web Service API. The API calls can be grouped in 4 categories:

• Project related calls

• Project Request related calls

• Offer related calls

• Bid related calls

Project related calls handle the creation, modification and deletion of Projects The following 5 calls

are implemented:

• Get Project Info – Get detailed information about a Project.

• Get Project List – Get a list of Projects

• Create Project – Create a new Project.

• Update Project – Update the information of a Project.

• Delete Project – Delete a Project.



48

Project Request related calls handle the creation, deletion and modification of Project Proposals The

following 5 calls are implemented:

• Get Project Request Info – Get detailed information about a Project Request.

• Get Project Request List – Get a list of Project Request s

• Create Project Request – Create a new Project Request.

• Update Project Request – Update the information of a Project Request.

• Delete Project Request – Delete a Project Request.

Offer related calls handle the creation, deletion and modification of Offers for Project Proposals The

following 5 calls are implemented:

• Get Offer Info – Get detailed information about an Offers.

• Get Offer List – Get a list of Offers for a Project Request.

• Create Offer – Create a new Offer for a Project Request.

• Update Offer – Update Offer information.

• Delete Offer – Delete an Offer.

Bid related calls handle the creation, deletion and modification of Project Bids The following 5 calls

are implemented:

• Get Bid Info – Get detailed information about a Bid.

• Get Bid List – Get a list of Bids for a Project.

• Create Bid – Create a new Bid for a Project.

• Update Bid – Update Bids information.

• Delete Bid – Delete a Bid.

4.6.2 Requirements for the Presentation tier

The home page will provide a random list of projects that need funds. The user will also have the

following options:

Discover a Project

This area contains a list of projects that need financial support. Bidders will be able to bid for its

creation.

Create a Project

This option will allow the creation of a new project. Providers who need financial support can

describe the project, set a fund raising goal and set a deadline for raising funds.

Propose a Projects



49

This option will allow a Consumer to make a project proposal. Providers can select the proposal and

create a new Project. When a Consumer creates a new proposal, the Providers will receive a

notification email.

View Proposals

This area contains a list of project proposals created by Consumers. Any Provider can explore the

proposals and make an offer if they want to implement the project. The Consumer will receive a

notification email if his proposal is accepted.

User Menu

This option is visible for authenticated users only. The users will be able to manage their projects,

proposals and bids.

Sign Up/Sign In

The crowd funding platform makes use of the Security – IAM (Identity and Access Management)

component. The Sign Up and Sign In options will redirect the user to Identity and Access

Management in order to complete his registration or sign in to the platform. On a successful sign in,

the user will redirect back to the current page.

Indicative screenshots follow:

Figure 33: Crowd funding Home page



50

Figure 34: Create a new Project Proposal

Figure 35: User visits a projects page in order to support this project



51

5 DeveloperSpace

The DeveloperSpace is the new online resource for anyone wanting to develop or market assistive technologies or access features in mainstream information and communication technologies.

5.1 The Big Picture The centerpiece and repository of the Prosperity4All work is the DeveloperSpace and it interconnected resource the Unified Listing. As part of the Prosperity4All project, the Unified Listing (which began in Cloud4all as an AT resource) was integrated in the DeveloperSpace infrastructure, and extended to cover mainstream technologies and user-developer connections. It was also enhanced with new AT databases. The Unified Listing now offers a complete directory of resources and the ICT portions of major databases of AT globally, as well as including access features in mainstream products. It was also integrated into the DeveloperSpace in a way that both facilitates the interaction between AT and mainstream manufacturers/developers and Consumers, acting as a broker between the two groups, and providing resources to link them. Figure 36 provides an overview of the relationship between the DeveloperSpace the Unified Listing and its federated partners and users.

Figure 36 Integration of the Unified Listing into the DeveloperSpace infrastructure

Animations showing the different flows of information and interaction between the users can be found on the DeveloperSpace website at the following locations

• Developers creating a new assistive technology. (https://ds.gpii.net/develop/components - https://ds.gpii.net/market/gpii-unified-listing)

• Customers providing feedback to manufacturers. (https://ul.gpii.net/content/ruby-7-hd?search_api_views_fulltext=camera - https://ul.gpii.net/search?search_api_views_fulltext=light+small+camera+that+is+voice+operated+and+self+aiming - https://ds.gpii.net/challenges)

• Companies looking for testers for their developments. https://ds.gpii.net/connect/testers


https://ds.gpii.net/develop/components

https://ds.gpii.net/market/gpii-unified-listing

https://ul.gpii.net/content/ruby-7-hd?search_api_views_fulltext=camera


https://ul.gpii.net/search?search_api_views_fulltext=light+small+camera+that+is+voice+operated+and+self+aiming

https://ul.gpii.net/search?search_api_views_fulltext=light+small+camera+that+is+voice+operated+and+self+aiming

https://ds.gpii.net/challenges

https://ds.gpii.net/connect/testers


52

• Manufacturers wanting to market their products. (https://ul.gpii.net/content/how-add-your-product-unified-listing )

• Users of the Unified Listing provide feedback and requests to Developers. (https://ul.gpii.net/content/ruby-7-hd?search_api_views_fulltext=camera)

Figure 37 provides a diagram (based on UML use case and component diagrams) for the DeveloperSpace showing the roles and benefits of the DeveloperSpace to different user groups as well as some of the ways it connects them to each other.

Figure 37 Interaction between Stakeholders and the DeveloperSpace / Unified Listing

5.2 Developers creating a new assistive technology. Developers can use components from the “Develop” section to help them create the product faster, and also save on development costs. The DeveloperSpace includes components, code, tools, frameworks and service infrastructure that can be used as components or models for access features or suites. Figure 38 show the components library in the DeveloperSpace as of the end of the project. More components have been added since then and we have about 300 more components in process.


https://ul.gpii.net/content/how-add-your-product-unified-listing

https://ul.gpii.net/content/how-add-your-product-unified-listing



53

Figure 38 Component directory and search option in the Unified Listing

In addition to the components there is also a LEARN section with a rich collection of resources and one-of-a-kind reference documents and quicksheets summarizing information and resources from across the web. Figure 39 shows the MasterList of Accessibility Strategies, a unique resource drawing from experts around the world and compiling all of the known strategies for providing access along with resource pages on each.

Figure 39 The MasterList of Accessibility Strategies, one component in the LEARN section of the DeveloperSpace



54

When they are done and ready to market it, developers can use the marketing component of the DeveloperSpace and the Unified Listing to project their product worldwide. This would apply to both assistive technology developers as well as mainstream product manufacturers who would like to make the access features in their products more widely known and used. Entering an AT product into the Unified Listing also makes it available through all of the databases that are federated with the Unified Listing. This currently includes databases throughout Europe, the United States and Australia.

Figure 40 The Unified Listing and the databases it is federated with



55

5.3 Customers providing feedback to manufacturers. Customers can use the feedback features of the Unified Listing to provide feedback to the manufacturers regarding product features they would like to see in individual products - or can provide information on future products they would like to see. Feedback information goes to the specific manufacturer, and also, if it is general in nature, to the DeveloperSpace in general for use by other developers. Information on future products goes to the DeveloperSpace as desired features or challenges/grand-challenges for developers or researchers.

Figure 41 Feedback features on each product page

Figure 42 Feedback/request feature on every search results listing

Figure 43 Challenges page in the DeveloperSpace



56

Some comments are feedback regarding existing designs, some are feedforward suggesting new products or features and some are feedpeer to other users helping them make better selections or better use of their existing products. Together these are referred to as the Feed3 features. Briefly they are:

1. Search page feature: when users are searching for products - and can't find what they need - they can use the feature on the search page to send a comment to developers and vendors describing the type of product they need and would like to see.

2. Product page feature: when users are viewing any product (one they have or one they are shopping for) they may leave comments for the manufacturer about features or improvements they would like to see. If these also apply to other products, the comments are also fed to the DeveloperSpace as new ideas or challenges.

3. Hints and tips between users: users may leave hints and tips to other users about the product they are viewing. For example, a user may mention that a product conflicts with another, or may point at a glitch and provide a suggestion in how to make it work, or highlight a really interesting feature of product for its specific advantages.

The goal is to offer a complete loop where the “feature request” led to development of the capability, its posting to the Unified Listing (and all of the federated databases) and availability to users.



57

5.4 Companies looking for testers for their developments. The DeveloperSpace offers different ways to engage end-users into the development process. A major need for Developers, is the ability to identify, contact and engage end-users, to help them during the design and development phases of their solutions. The DeveloperSpace invites end users to help build better solutions by volunteering in the development process. To do so, the user can register themselves and the type of ICT they would be interested in being a tester for.

Figure 44 Consumer “Tester” signup page in the DeveloperSpace

Simultaneously, developers looking for testers of their new product can send a query to the DeveloperSpace, and tap into the volunteer database. The developers’ query results in a notification to the potential testers, users who match the developers’ needs - giving them the developer’s contact information. For privacy and ethical reasons, the end-users are responsible for contacting the developers directly. The DeveloperSpace never shares testers identities or contact information with the Developers.



58

5.5 Manufacturers wanting to market their products. Manufacturers can now add their products to the Unified Listing by filling out a simple form, which will provide curators with basic information and a link to the manufacturer’s product page. When a new product is added, it is instantly included in the appropriate databases, depending upon if it's a mainstream database or an assistive technology.

Figure 45 Adding products page in the Unified Listing

When a manufacturer updates a product, changes, are automatically fed back to the different federated databases around the world.



59

6 Quality Infrastructure

The Quality Infrastructure is a collection of build and test automation tools accompanied by a user interface dashboard that provides information and metrics about the quality and sustainability of components in the DeveloperSpace. The goal of the Quality Infrastructure is to lower the barrier and costs associated with sustainable software development practices, including:

• Automated unit and acceptance testing • Automated accessibility checking • Continuous integration of builds and tests (i.e. completely rebuilding and testing the

entire system whenever it changes)

Each of these practices contributes to software that is more robust, maintainable, easier to contribute to, and less prone to regressions over time. However, such practices also require significant technical infrastructure—both on developers’ client machines as well as servers—to successfully integrate into the cross-platform, distributed workflows common amongst developers today. Supporting automated builds of native applications (in addition to web-based software) on Windows and Linux is particularly challenging and expensive to implement; current commercial and open source providers do not offer integrated solutions that fully support Windows virtualization. Prior to the Quality Infrastructure, developers who wanted to practice cross-platform continuous testing and integration have been required to roll their own ad-hoc solutions by piecing together a variety of poorly supported components for each task, typically resulting in expensive, unmaintainable “black box” systems.

To address this, the Prosperity4All Quality Infrastructure offers a collected and fully integrated set of tools, automation playbooks, and testing resources that make it significantly easier and cheaper to get up and running with software quality practices. The Quality Infrastructure includes support for automating:

• Native unit tests running within multiple environments using virtual machines: Windows, Linux, and Docker

• Browser-based testing across all browsers supported on Mac, Windows, and Linux using Testem

• Automated acceptance tests using Selenium and WebDriver • Accessibility evaluation using aXe • Notification of build status for pull requests and code changes submitted to GitHub

In addition, the Quality Infrastructure provides a user interface dashboard that can be integrated into web applications such as the Prosperity4All DeveloperSpace, which shows



60

graphs and information about the current and historical status of commits, test results, and contributions to an open source project.

The complete architecture and technical design of the Quality Infrastructure is described in depth in D201.1, Specification of Architecture, Security, Payment Infrastructure and DeveloperSpace.

6.1 Status of the Quality Infrastructure Implementation

The Quality Infrastructure has been developed using a variety of programming languages and tools. We heavily employed third-party libraries wherever possible to reduce the amount of work required, but emphasized the use of Vagrant, Node.js and JavaScript. The Quality Infrastructure’s source code is developed and distributed freely on Github under the 3-Clause BSD license19. The developers of the Quality Infrastructure have adopted the GPII’s rigorous open source technical governance policies and collaborative community practices, which means that it has been frequently code reviewed and tested. These practices were adopted to help support the sustainability of the Quality Infrastructure beyond the end of Prosperity4All’s funding period.

Support for automated builds and testing of Node.js applications was implemented first, using virtual machines running CentOS and Fedora Linux. Subsequently, we added support for virtualized builds on Windows, which took the bulk of the project’s effort because there are significantly fewer well-tested “devops” solutions available on Windows20. As part of this, we developed a custom solution for remotely executing tests and build commands within a Windows-based virtual machine using WinRM and the DoIT library.

Three different continuous integration tools were evaluated and integrated into the Quality Infrastructure. This was another area of significant complexity and difficulty, since the only open source solution—Jenkins—is old, unreliable, and in many cases dependent on unsupported, poor-quality plugins21. The only alternatives are commercial hosted services, many of which are overly bundled into “full stack” solutions that include version management, issue tracking, and other functionality all in one. We have developed Quality Infrastructure service connectors for Jenkins22, GitLab23, and BuildKite24, and all three are in

19 The primary Github repository for the Quality Infrastructure is: https://github.com/GPII/qi-development-environments 20 Developer Operations, or devops, is a software engineering practice that aims to support automation at all steps of the software construction lifecycle. Devops is the primary strategy that the Quality Infrastructure aims to make easier for small, open source teams. https://en.wikipedia.org/wiki/DevOps 21 https://jenkins-ci.org/ 22 QI Jenkins connector: https://github.com/GPII/ci-service 23 QI GitHub and GitLab integration: https://github.com/avtar/docker-push-ref-gitlab 24 QI BuildKit integration: https://github.com/avtar/unblock-buildkite-pr-job



61

use by different projects who have integrated with the QI. We recommend that new developers use BuildKite with the Quality Infrastructure, due to its simplicity to configure relative to the others.

Documentation25, a tutorial26, and several videos27 have been all published to help support developers when using the Quality Infrastructure.

The Quality Infrastructure’s build and test automation tools are now an essential part of the development workflow of several major open source projects that feature many contributors, including: the GPII autopersonalization system, Fluid Infusion, Flocking, osc.js, the Nexus, and others.

A user interface dashboard has also been developed, which provides information about the status and state of open source projects that use the Quality Infrastructure or other community tools such as GitHub. This helps prospective users of components in the DeveloperSpace determine if a codebase is sufficiently active, tested, and contributed to when they are finding and evaluating their options. Developers can see graphs displaying number of commits, amount of contribution, and continuous integration build and test results28. This dashboard was integrated into a development version of the DeveloperSpace, and is currently being integrated into the updated, production version of it.

25 Quality Infrastructure documentation on the GPII wiki: https://wiki.gpii.net/w/Quality_Infrastructure 26 Quality Infrastructure tutorial: https://github.com/avtar/qi-development-environments/tree/GPII-1865 27 An Introduction to the Quality Infrastructure: https://www.youtube.com/watch?v=-zU3odcXln0 and Quality Infrastructure Update: https://www.youtube.com/watch?v=YcaSnUCZQhY 28 A demonstration version of the QI Dashboard is available: https://qi.gpii.net/demos/noJquery-basic.html



62

Figure 46: Screenshot of the Quality Infrastructure Dashboard, showing graphs for the number of commits and contributors over time

6.2 Future Work

The Quality Infrastructure has become a crucial part of several open source community development workflows; more work is needed to address the needs that have emerged from such extensive real-world usage. Work will continue after the end of Prosperity4All’s funding period. In particular, new higher-level abstractions and a simpler manifest file format are planned, as well as greater orchestration support for test execution across multiple, concurrently-running virtual machines and containers, based on the Quality Infrastructure’s Vagrant Plugin infrastructure29.

29 The Quality Infrastructure’s vagrant plugin is used to simplify the provisioning of virtual machines for testing. https://github.com/amatas/vagrant-gpii-ci



63

7 The Nexus

The Nexus is an integration technology that helps developers more easily combine software and hardware components that have been developed using different programming languages, frameworks, and protocols. Its goal is to reduce the cost of software reuse within the Prosperity4All ecosystem, particularly in situations where heterogeneous technologies must be integrated—often a source of added complexity and cost in traditional architectures.

The unique innovation of the Nexus approach centers around the practice of state externalization, which stands in contrast to the prevailing tendency to insulate and hide state via APIs and object interfaces, which can present barriers to reuse and the creation of alternative user interfaces. Instead, the Nexus encourages developers to define and share “avatars” in the form of Nexus components, which provide different working representations of a remote (or local) system. This approach to state externalization, the concept of avatars, and our implementation of it in the Nexus are described in depth in “Tracing a Paradigm for Externalization: Avatars and the GPII Nexus” (Clark and Basman 2017).30

Specifically, the Nexus provides a means by which developers can define and externalize:

1. the state of components and applications (called “models” in the Nexus’ terminology)

2. model relays that notify clients when changes occur within a graph of component state

3. co-occurrence rules (called “recipes”), which will create components, establish relays amongst them, and destroy them based on the presence (or absence) of dependent component groupings

The Nexus also includes a visualization environment, called the Visible Nexus, which presents the structure of components and their model relays in a graphical form, including dynamic highlighting of changes to model fields as they occur.

7.1 The Co-Occurrence Engine

The Nexus Co-Occurrence Engine is an add-on module for the Nexus that allows developers to establish dynamically responsive relationships between components running within a

30 Clark, Colin and Antranig Basman. “Tracing a Paradigm for Externalization: Avatars and the GPII Nexus.” In: Companion to the First International Conference on the Art, Science and Engineering of Programming. 2017. https://dl.acm.org/citation.cfm?id=3079410



64

Nexus instance. Co-occurrence recipes can be registered with the Nexus, containing definitions of:

• Reactants—components whose creation or destruction can trigger the creation or destruction of other components

• Products—the components that are dynamically created by the co-occurrence engine when all reactants are present

All components within the Nexus are structured in a component tree, which defines a scope for resolution of references amongst components. The Co-Occurrence Engine can be bound to any component within the tree, which forms the engine’s “component root.” The Engine then watches for components being constructed and destroyed under the component root. When a new component is created, the Co-Occurrence Engine checks its recipes for reactant matches, creating any products as appropriate. When a component is destroyed, all recipe products that use the destroyed component as a reactant are also destroyed. Each reactant has:

• A name that uniquely defines it within the recipe • A match description, which contains rules that are checked against the components

under the Co-Occurrence Engine component root

Below is an example co-occurrence recipe entry. Here, reactants are defined by a single match criteria, which tests against the type (called a “grade name” in the Nexus’ terminology) of all newly-instantiated components in the Nexus: { gradeNames: [ "gpii.nexus.recipe" ], reactants: { phSensor: { match: { type: "gradeMatcher", gradeName: "gpii.nexus.atlasScientificDriver.phSensor" } }, collector: { match: { type: "gradeMatcher", gradeName: "gpii.nexus.scienceLab.collector" } } }, product: { path: "sendPhSensor", options: { type: "gpii.nexus.scienceLab.sendPhSensor" } } }

Example of a Nexus Recipe in which two reactants, representing a pH sensor and a data collector, will trigger the creation of a new data-sending relay (called “sendPhSensor”) between the two components whenever they are both present.



65

An integration of the Nexus was developed that specifically illustrates the value of the Co-Occurrence Engine when creating multiple representations of data streaming from different types of hardware devices. For the Inclusive Science Lab, the Nexus was used to help develop a more accessible and physically-engaging science lab environment that allows students to see, hear, and read the results of science experiments in real time. We used the Co-Occurrence Engine to dynamically connect lab sensors, such as pH sensors and electrical conductivity sensors, to a range of different visual, textual, and sonic presentations and interactions. The goal is to help students find the interaction that works best for their personal needs and learning style. For some students, this might be a visualization and for others it might be a sonification, or a combination of different presentations. We co-designed the Inclusive Science Lab with elementary school-aged students, and a video was published that demonstrates the science lab and describes how the Nexus’ Co-Occurrence Engine supported it31.

7.2 The Visible Nexus

The Visible Nexus was developed to provide Nexus users with improved tools for understanding and debugging their applications. It offers a live, node-based graphical environment in which the current state of the Nexus’ component tree can be visualized and edited. The Visible Nexus’ user interface is also keyboard navigable and compatible with assistive technologies such as screen readers, so it is also accessible.

Like the Co-Occurrence Engine, the Visible Nexus is an module that may be added to an instance of the Nexus. Once added, it provides a self-served web interface that allows the contents of the Nexus to be queried, represented in a visual graph form, and manipulated.

The current implementation demonstrates the essential affordances of the system. Any numbers of clients may simultaneously connect to the same Nexus interface and interact with the same shared substrate. Any updates to the component structure or the models attached to the components, whether triggered internally or by one of the clients, are immediately transmitted to the UIs of any connected clients.

31 Nexus Inclusive Science Lab Demonstration video on YouTube: https://www.youtube.com/watch?v=NNwc0VYRhUU



66

Figure 47: A screenshot of the Visible Nexus application, showing a tree of components for the Inclusive Science Lab application. Model fields highlighted in yellow are ones that have recently changed as the result of incoming hardware sensor data.

After developing the Visible Nexus prototype, we performed an extensive usability evaluation of the Visible Nexus user interface based on the UX Walkthroughs technique described in the Prosperity4All Inclusive Design Guide, part of the project’s SP1 deliverables32. To evaluate the potential benefits and challenges of the Visible Nexus for developers and end users, our team used several SP1 user personas and use cases as the basis for the UX walkthrough33.

We chose to work with James (AT developer persona), Nora (researcher/ educator persona), and Nicholas (a young student with cerebral palsy) in order to explore how different users can use the Visible Nexus through the DeveloperSpace, and how they can each benefit from this technology34.

32 https://guide.inclusivedesign.ca/tools/UXWalkthroughs.html 33 These personas and use cases are defined in the Prosperity4All Use Model: https://wiki.gpii.net/w/Use_model 34 The raw notes from this UX evaluation are available: https://docs.google.com/document/d/199yvZICri6hWho6JSZMpo_XMixeHG0k2MKl8JVg7Jk4


https://wiki.gpii.net/w/Use_model#AT_Developer

https://wiki.gpii.net/w/Use_model#AT_Researcher.2FEducator

https://wiki.gpii.net/w/Use_model#End_User_.28more_than_4_barriers.29


67

Resulting from this evaluation process, we have significantly redesigned the user interface of the Visible Nexus to better represent the different kinds of relationships that can be defined amongst Nexus components. Specifically, our aim was to clarify the differences between containment relationships within the component tree hierarchy and the cross-cutting relationships of model relays and their associated transformation operations.

Figure 48: A mockup of the new user interface for the Visible Nexus, which improves the visual design and layout of the system. This design more clearly distinguishes between the component tree containment hierarchy (represented as solid, Bezier-curved lines) and

7.3 Status of the Nexus Implementation

The Nexus is implemented in JavaScript using the Node.js runtime. The Nexus is transport-agnostic, and we have developed bindings for the Nexus API that can be used over the HTTP and WebSocket protocols. These local and remote APIs are documented in detail in D201.1, and reference documentation for developers has also been published openly on the GPII wiki35.

35 Nexus API Documentation: https://wiki.gpii.net/w/Nexus_API



68

The Nexus source code is developed and distributed freely on Github under the 3-Clause BSD license. The developers of the Nexus have adopted the GPII’s rigorous open source technical governance policies and collaborative community practices, which means it has been heavily code reviewed, unit tested, and integrated into the Prosperity4All’s Quality Infrastructure.

The Nexus is highly modular. At the physical dependency level, it is factored into four discrete modules and associated source code repositories, enabling portions of the Nexus’ overall functionality to be used independently. A “distribution” repository, called nexus-dist, contains an all-in-one package consisting of the Nexus itself, the Co-Occurrence Engine, and the Visible Nexus application36. This repository is the recommended starting point for developers who are interested in using the Nexus in their own application.

In addition, the Nexus package includes automated scripts that enable developers to run the Nexus securely on their local computers or on a server using a Docker container. This containerized mode supports all major operating systems (Windows, macOS, and Linux) and includes a seccomp-based security infrastructure that isolates the components running within a Nexus instance from the host system and prevents them from accessing privileged system calls or making unauthorized network connections37.

Figure 49 The Nexus’ module and repository structure.

The Nexus has also been published on the NPM JavaScript package repository so that it can be more easily be used as a building block within other JavaScript-based applications38.

The essential functionality of the Nexus, allowing developers to integrate different software components and hardware devices using an API that unifies them via externalized state transfer, is complete. In addition, the Co-Occurrence Engine enables the creation of dynamic

36 https://github.com/GPII/nexus-dist 37 seccomp is a kernel-based security system that isolates processes and prevents them from system calls that are not specifically authorized by a whitelist. https://en.wikipedia.org/wiki/Seccomp 38 https://www.npmjs.com/package/gpii-nexus



69

bindings between Nexus components, and the Visual Nexus provides a viable means for displaying, inspecting, and debugging Nexus-based applications live. Several relatively complex integrations of the Nexus—including the Nexus Musical Instrument project and the PhET John Travoltage simulation that are outlined in D302.1, Description of FLOE Resources and Tutorials, as well as the aforementioned Inclusive Science Lab Environment—have been developed to exert the Nexus’ capabilities in the context of real assistive technologies that combine different hardware and software components together.

7.4 Future Work

Further work is planned on the Co-Occurrence Engine beyond the scope of Prosperity4All. In particular, the addition of new predicate types expressed in a CSS-like syntax will allow developers to create more complex recipes based on “selectors” that can match a variety of live component characteristics. Additionally, the Nexus API will be used within the GPII autopersonalization system to establish a cross-process assistive technology configuration bus that will make it easier to integrate on-the-fly changes to applications by the GPII. The Visible Nexus’ user interface will continue to be refined based on the results of usability testing with developers.



70

8 Conclusion

The Prosperity4All technical architecture is comprised of a loosely-coupled collection of tools, frameworks, and applications that are designed specifically to support the creation of assistive technologies and accessible applications more quickly, more cost-effectively, and more securely. By providing solutions that take of the complex, precious essentials of accessible software architectures in a reusable manner, the tools described in this document provide a greater opportunity for accessibility developers to focus on their applications’ own unique innovations, rather than on building and rebuilding the time-consuming scaffolding and infrastructure that are required for security, payment, integration, quality, and discovery. In each case, the Prosperity4All Security-IAM tools, payment and crowdfunding infrastructure, Quality Infrastructure, Nexus, and DeveloperSpace have been developed, released, and used as open source software along with the tutorials, documentation and resources required to understand, use, and extend them.



71

9 Annex I

9.1 Security APIs The registration of an application is the first step to integrate with the IAM. The final step is the full integration between the registered application and the IAM. This can be achieved by adding business logic as a module in the application. IAM infrastructure (OpenAM API, IAM API) provides a set of web services to the application that:

• Authenticate the user • Authorize the user

o Retrieve the access token o Retrieve the basic or extended user profile o Retrieve the role(s) of user (a user could have more that one role)

• Manage the access token o Validate the access token o Update the access token

Any application protected through the IAM infrastructure has to redirect the browser of any end-user that requires access to it towards the IAM login form for authentication. Therefore, the user’s browser must be redirected to a URL with the following pattern:

GET http://83.235.169.221/prosperity4all/identity-access-manager/oauth2/authorize/?response_type=code&client_id={CLIENT_ID}&redirect_uri={CALLBACK_URL}

where the CLIENT_ID value has been generated during the registration of the application and characterizes it uniquely, and the CALLBACK_URL value has been provided by the application owner during the registration and is made available by the application. These parameters are known both to the IAM infrastructure and the application side. There, the end-user must enter his/her credentials and submit them. The IAM infrastructure receives the request and evaluates the credentials. Given that the user has entered valid credentials, IAM generates the AUTHORIZATION_CODE and redirects the end-user’s browser to the CALLBACK_URL providing the CODE as a query parameter. The redirect URL must have the following pattern:

GET {CALLBACK_URL}?code={CODE}

The application receives the authorization code given that the end-user has redirected to CALLBACK_URL. Therefore, the application can request an access token from IAM infrastructure using the CLIENT_ID, CLIENT_SECRET, and AUTHORIZATION_CODE received. The IAM infrastructure validates the application credentials and authorization code and returns an access token to the application. To achieve it, the application invokes the web service that is described in Table 1.

Table 1: Web service that provides the access token upon request (part of OpenAM API)

HTTP method

POST



72

Endpoint http://83.235.169.221/openam/oauth2/access_token

HTTP headers

Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Basic {token} -> encode_base64(CLIENT_ID:CLIENT_SECRET)

Payload grant_type=authorization_code&code={AUTHORIZATION_CODE}&redirect_uri={CALLBACK_URL}

Normal Response

Status: 200 OK { "scope": "email openid profile", "expires_in": integer, "token_type": "Bearer", "refresh_token": "string", "id_token": "string", "access_token": " string " }

Erroneous response

Status: 400 BAD REQUEST { "error": "invalid_grant", "error_description": "The provided access grant is invalid, expired, or revoked." }

The web service returns a JSON object. It includes the access token, the refresh token and the expiration period in seconds. The application should store at least the access token for future usage either in the database or in another type of storage. It is suggested to keep both access and refresh tokens.

Since the access token of the end-user is known and stored, the application could retrieve the basic or the extended end-user profile. The web service that provides the basic end-user profile is presented in Table 2. If the access token is valid, the web service returns a JSON object including the username of end-user (sub field), his/her email, first name and surname.

Table 2: Web service that provides the basic end-user profile upon request (part of OpenAM API)

HTTP method GET

Endpoint http://83.235.169.221/openam/oauth2/userinfo

HTTP headers Accept: application/json Content-Type: application/json Authorization: Bearer {access_token}

Payload -

Normal Status: 200 OK



73

Response { "sub": "string", "updated_at": "string", "email": "email", "name": "string", "family_name": "string", "given_name": "string" }

Erroneous response

Status: 400 BAD REQUEST { "error": "server_error", "error_description": "Access Token not valid" }

The web service that provides the extended end-user profile is presented in Table 3. If the access token is valid, the web service returns a JSON object including the username, email, phone, residence details, familiarity with it services (IT skills) and crowd-funding preferences (applicable in the case of the AoD users).

Table 3: Web service that provides the extended end-user profile upon request (part of IAM API)

HTTP method GET

Endpoint http://83.235.169.221/prosperity4all/identity-access-manager/api/oauth2/userinfo?access_token={access_token}

HTTP headers Accept: application/json

Payload -

Normal Response

Status: 200 OK { "name": "string", "surname": "string", "gender": "enum(M, W)", "username": "string", "country": "string", "city": "string", "address": "string", "postcode": "string", "mail": "email", "phone": "string", "skills": "enum(low, normal, high)", "crowd_fund_participation": "boolean", "crowd_fund_notification": "boolean"



74

}

Unauthorized response

Status: 401 UNAUTHORIZED { "reason": "Access Token is not valid", "code": 401 }

Assuming that the application has the access token of the end-user, it could retrieve the roles of end-user providing the access token and the CLIENT_ID. To perform it, the web service that is described in Table 4 is used. If the access token is valid, the web service returns a list of JSON objects including the application’s CLIENT_ID and name, and the name of role (application_role.role.type).

Table 4: Web service that provides end-user roles per application upon request (part of IAM API)

HTTP method GET

Endpoint http://83.235.169.221/prosperity4all/identity-access-manager/api/oauth2/roles?access_token={access_token}&client_id={client_id}


Payload -

Normal Response

Status: 200 OK [ { "application_role": { "application": { "client_id": "string", "name": "string" }, "role": { "type": "string" } } } ]


Status: 401 UNAUTHORIZED { "reason": "Access Token is not valid", "code": 401 }

Erroneous client Status: 404 NOT FOUND



75

response { "message": "Client_id is not valid", "code": 404, "reason": "Not found" }

The OpenAM API exposes a web service that validates the access status of an end-user for a given application. If the access token is active and valid, then the http status of response is 200. In any different case, the access token either has revoked or has expired.

Table 5: Web service that validates an existing access token (part of OpenAM API)

HTTP method GET

Endpoint http://83.235.169.221/openam/oauth2/tokeninfo?access_token={access_token}

HTTP headers Accept: application/json Content-Type: application/json

Payload -

Normal Response

Status: 200 OK { "scope": [ "email", "openid", "profile" ], "grant_type": "authorization_code", "email": "string", "realm": "/", "openid": "string", "token_type": "Bearer", "expires_in": "integer", "access_token": "string", "profile": "string" }

Erroneous response

Status: 400 BAD REQUEST { "error": "invalid_request", "error_description": "Access Token not valid" }



76

The OpenAM API provides a web service that extends an existing access token. In case that the access token (that the application has stored) is not valid, there are two options with respect to access token refresh. The most obvious option is to redirect the end-user’s browser to the IAM login page and require from the end-user to enter his/her credentials again. An alternative option is to try to refresh the access token using the stored refresh token using the web service described in the Table 6. If the refresh token is still valid, the web service returns a new JSON object that includes a valid access token, an updated refresh token and the expiration period of access token in seconds.

Table 6: Web service that refreshes an invalid access token using the refresh token (part of OpenAM API)

HTTP method POST

Endpoint http://83.235.169.221/openam/oauth2/access_token

HTTP headers Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Basic {token} -> encode_base64(client_id:client_secret)

Payload grant_type=refresh_token&refresh_token={refresh_token}

Normal Response

Status: 200 OK { "scope": "email openid profile", "expires_in": "integer", "token_type": "Bearer", "refresh_token": "string", "id_token": "string", "access_token": "string" }


Status: 401 UNAUTHORIZED { "error": "invalid_client", "error_description": "Client authentication failed" }

Erroneous response

Status: 400 BAD REQUEST { "error": "invalid_grant", "error_description": "grant is invalid" }



77

9.2 Payment APIs The Payment API provides a set of web services to perform instant, recurring or future payment transactions and generate reports. In practice, the web services related to payment transactions act as wrappers of the existing Paypal REST services. Further HTTP headers are required in order to ensure that:

• the P4A application that invokes the Payment API is trusted and integrated with the IAM infrastructure (Openam-Client header),

• the user is registered in the IAM infrastructure and has a valid access token (Openam-Client-Token header),

• the P4A application has a valid access token in Paypal (Paypal-Access-Token header).

Table 7 and Table 8 displays useful web services provided by the Paypal REST API and Paypal API. During the development phase, the sandbox environment of Paypal was used to avoid any charge (testbed for developers).

Table 7: Useful endpoints of Paypal REST API

Method Paypal endpoint Description

POST https://api.sandbox.paypal.com/v1/oauth2/token Generates the access token in Paypal based on provider application credentials

POST https://api.sandbox.paypal.com/v1/notifications/webhooks Subscribes your webhook listener to events

POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/{agreement-id}/cancel

Cancels an existing billing agreement

Table 8: Useful endpoints of Payment API

Method Payment endpoint Description

POST https://83.235.169.221:443/api/v1/payments/payment Creates a sale, an authorized payment to be captured later, or an order

POST https://83.235.169.221:443/api/v1/payments/payment/{payment-id}/execute

Executes a PayPal payment that the customer has approved

POST https://83.235.169.221:443/api/v1/payments/billing-plans Creates a billing plan

PATCH https://83.235.169.221:443/api/v1/payments/billing-plans/{plan-id}

Activates a billing plan

POST https://83.235.169.221:443/api/v1/payments/billing-agreements

Creates a billing agreement

POST https://83.235.169.221:443/api/v1/payments/billing-agreements/{payment-token}/agreement-execute

Executes a billing agreement after customer confirmation

POST https://83.235.169.221:443/api/v1/notifications/webhooks Receives and handles the Paypal notifications


https://api.sandbox.paypal.com/



https://83.235.169.221/

https://83.235.169.221/

https://83.235.169.221/

https://83.235.169.221/

https://83.235.169.221/

https://83.235.169.221/

https://83.235.169.221/


78

9.2.1 Authorize P4A application through Paypal REST API

Paypal provides a web service that generates the access token based on the credentials of the service provider’s application in Paypal using its RESTful web service39 (see Table 9). These credentials compose an authorization token according to the transformation base64_encode(client_id:client_secret).

Table 9: Generate an access token in Paypal

HTTP method POST

Endpoint https://api.sandbox.paypal.com/v1/oauth2/token


Content-type: application/x-www-form-urlencoded Authorization: Basic {token}

Payload grant_type=client_credentials

Expected http status 200 OK

Expected Response

{ "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*", "nonce": "2016-11-25T09:22:01Zdx1H53OFBMt16kG0k5oDQu6e6Hx7CEvzFg-AB3i5x3I", "access_token": "abc", "token_type": "Bearer", "app_id": "APP-XXXXXX", "expires_in": 30311 }

It’s worth to stress that the generated access token is required in case of Paypal API and Payment API calls. This access_token will be referred in the rest section as paypal_access_token.

9.2.2 Establish a notification listener in Payment API (webhook)

The PayPal REST APIs use webhooks40 for event notification (see Table 10). Webhooks are HTTP callbacks that receive notification messages for events. After you configure a webhook listener for your application, you can create a webhook, which subscribes the webhook listener for your application to events.

Table 10: Setup a webhook for your application

HTTP method POST

39 https://developer.paypal.com/docs/integration/direct/make-your-first-call/#get-an-access-token 40 https://developer.paypal.com/docs/api/webhooks/#webhooks_create




79

Endpoint https://api.sandbox.paypal.com/v1/notifications/webhooks

HTTP headers Content-type: application/json Authorization: Bearer {paypal_access_token}

Payload

{ "url": "https://83.235.169.221:443/api/v1/notifications/webhooks", "event_types": [ { "name": "PAYMENT.AUTHORIZATION.CREATED" }, { "name": "PAYMENT.AUTHORIZATION.VOIDED" }, … ] }

Expected http status 201 CREATED

Expected Response

{ "id": "XYZ", "url": "https://83.235.169.221:443/api/v1/notifications/webhooks", "event_types": [ { "name": "BILLING.PLAN.CREATED", "description": "This event is triggered when a billing plan is created." }, { "name": "BILLING.PLAN.UPDATED", "description": "This event is triggered when a billing plan is updated." }, { "name": "BILLING.SUBSCRIPTION.CANCELLED", "description": "This event is triggered when a billing subscription is cancelled." }, { "name": "BILLING.SUBSCRIPTION.CREATED", "description": "This event is triggered when a billing subscription is created." }, { "name": "BILLING.SUBSCRIPTION.RE-ACTIVATED", "description": "This event is triggered when a billing subscription is reactivated." }, { "name": "BILLING.SUBSCRIPTION.SUSPENDED", "description": "This event is triggered when a billing subscription is suspended." }, { "name": "BILLING.SUBSCRIPTION.UPDATED", "description": "This event is triggered when a billing subscription is updated." }, { "name": "CUSTOMER.DISPUTE.CREATED", "description": "A dispute was filed against a transaction" }, {




80

"name": "CUSTOMER.DISPUTE.RESOLVED", "description": "A dispute was closed against a transaction" }, { "name": "IDENTITY.AUTHORIZATION-CONSENT.REVOKED", "description": "An event for identity consent revocation" }, { "name": "INVOICING.INVOICE.CANCELLED", "description": "An invoice has been cancelled" }, { "name": "INVOICING.INVOICE.PAID", "description": "An invoice has been paid" }, { "name": "INVOICING.INVOICE.REFUNDED", "description": "An invoice has been refunded" }, { "name": "MERCHANT.ONBOARDING.COMPLETED", "description": "The merchant account setup is completed" }, { "name": "PAYMENT.AUTHORIZATION.CREATED", "description": "A payment authorization was created" }, { "name": "PAYMENT.AUTHORIZATION.VOIDED", "description": "A payment authorization was voided" }, { "name": "PAYMENT.CAPTURE.COMPLETED", "description": "A capture payment was completed" }, { "name": "PAYMENT.CAPTURE.DENIED", "description": "A capture payment was denied" }, { "name": "PAYMENT.CAPTURE.PENDING", "description": "A capture payment is pending" }, { "name": "PAYMENT.CAPTURE.REFUNDED", "description": "A capture payment was refunded" }, { "name": "PAYMENT.CAPTURE.REVERSED", "description": "A capture payment was reversed by paypal" }, { "name": "PAYMENT.PAYOUTS-ITEM.BLOCKED", "description": "A payout item was blocked" },



81

{ "name": "PAYMENT.PAYOUTS-ITEM.CANCELED", "description": "A payout item was canceled" }, { "name": "PAYMENT.PAYOUTS-ITEM.DENIED", "description": "A payout item was denied" }, { "name": "PAYMENT.PAYOUTS-ITEM.FAILED", "description": "A payout item has failed" }, { "name": "PAYMENT.PAYOUTS-ITEM.HELD", "description": "A payout item is held" }, { "name": "PAYMENT.PAYOUTS-ITEM.REFUNDED", "description": "A payout item was refunded" }, { "name": "PAYMENT.PAYOUTS-ITEM.RETURNED", "description": "A payout item is returned" }, { "name": "PAYMENT.PAYOUTS-ITEM.SUCCEEDED", "description": "A payout item has succeeded" }, { "name": "PAYMENT.PAYOUTS-ITEM.UNCLAIMED", "description": "A payout item is unclaimed" }, { "name": "PAYMENT.PAYOUTSBATCH.DENIED", "description": "Batch payouts got denied" }, { "name": "PAYMENT.PAYOUTSBATCH.PROCESSING", "description": "Batch payouts is getting processed" }, { "name": "PAYMENT.PAYOUTSBATCH.SUCCESS", "description": "Batch payouts is completed" }, { "name": "PAYMENT.SALE.COMPLETED", "description": "A sale payment was completed" }, { "name": "PAYMENT.SALE.DENIED", "description": "A sale payment was denied" }, { "name": "PAYMENT.SALE.PENDING", "description": "A sale payment is pending"



82

}, { "name": "PAYMENT.SALE.REFUNDED", "description": "A sale payment was refunded" }, { "name": "PAYMENT.SALE.REVERSED", "description": "A sale payment was reversed by paypal" }, { "name": "VAULT.CREDIT-CARD.CREATED", "description": "A credit card was created" }, { "name": "VAULT.CREDIT-CARD.DELETED", "description": "A credit card was deleted" }, { "name": "VAULT.CREDIT-CARD.UPDATED", "description": "A credit card was updated" } ], "links": [ { "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/3RG0389551938354J", "rel": "self", "method": "GET" }, { "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/3RG0389551938354J", "rel": "update", "method": "PATCH" }, { "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/3RG0389551938354J", "rel": "delete", "method": "DELETE" } ] }

9.2.3 Create and execute a payment through Payment API

The Payment API provides a web service to the P4A applications that enables service providers to make PayPal and credit card payments.

Table 11: P4A application creates a payment on demand

HTTP method POST

Endpoint https://83.235.169.221:443/api/v1/payments/payment


https://83.235.169.221/


83

HTTP headers

Accept: application/json

Content-type: application/json

Openam-Client: {openam_client_id} Openam-Client-Token: {the merchant’s access_token in the integrated with OpenAM application} Paypal-Access-Token: {paypal_access_token}

Payload

{ "intent": "sale", "payer": { "payment_method": "paypal" }, "transactions": [ { "amount": { "total": "30.11", "currency": "EUR", "details": { "subtotal": "30.00", "tax": "0.07", "shipping": "0.03", "handling_fee": "1.00", "shipping_discount": "-1.00", "insurance": "0.01" } }, "description": "Sale of service A", "custom": "AoD_90048630024435", "payment_options": { "allowed_payment_method": "INSTANT_FUNDING_SOURCE" }, "soft_descriptor": "AOD-34", "item_list": { "items": [ { "name": "Service A", "description": "Service A description", "quantity": "1", "price": 30, "tax": 0.11, "sku": "1", "currency": "EUR" } ] } } ], "note_to_payer": "Contact us for any questions on your order.", "redirect_urls": { "return_url": "http://83.235.169.221:8025/en/services/11/payment/execute", "cancel_url": "http://83.235.169.221:8025/en/services/11/payment/cancel" } }



84


Expected response

{ "id": 2, "payment": { "links": [ { "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9PK71013PB057862ULGXZ5DQ", "method": "GET", "rel": "self" }, { "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-4KJ62557F0057161B", "method": "REDIRECT", "rel": "approval_url" }, { "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9PK71013PB057862ULGXZ5DQ/execute", "method": "POST", "rel": "execute" } ], "payer": { "payment_method": "paypal" }, "transactions": [ { "item_list": { "items": [ { "sku": "1", "name": "Service A", "price": "30.00", "description": " Service A description", "tax": "0.11", "currency": "EUR", "quantity": 1 } ] }, "related_resources": [], "description": "Sale of service A", "payment_options": { "recurring_flag": false, "skip_fmf": false, "allowed_payment_method": "INSTANT_FUNDING_SOURCE" }, "custom": "AoD_90048630024435", "amount": { "currency": "EUR", "total": "30.11", "details": {



85

"shipping_discount": "-1.00", "tax": "0.07", "shipping": "0.03", "handling_fee": "1.00", "subtotal": "30.00", "insurance": "0.01" } }, "soft_descriptor": "AOD-34" } ], "state": "created", "create_time": "2017-09-06T07:06:53Z", "intent": "sale", "note_to_payer": "Contact us for any questions on your order.", "id": "PAY-9PK71013PB057862ULGXZ5DQ" } }

More details about the payload and the response of the web service in Table 11 are available here. You can set the intent variable to sale, authorize or order. A sale is a direct credit card payment, stored credit card payment, or PayPal payment. An authorized payment places funds on hold to be captured later. An order is a purchase that a customer has approved but for which the funds are not placed on hold. Keep in mind that the format of the response in our case is {“id”: “payment_component_id”, “payment”: “paypal_response_object”}. The payment-id should be stored by the P4A application for future usage is the response['payment']['id'] (PAY-9PK71013PB057862ULGXZ5DQ).

The Payment API provides a web service that executes a payment that the service consumer has already approved (see Table 12). For further details, take a look in the paypal guidelines (https://developer.paypal.com/docs/api/payments/#payment_execute).

Table 12: P4A application executes an approved payment

HTTP method POST

Endpoint https://83.235.169.221:443/api/v1/payments/payment/PAY-9PK71013PB057862ULGXZ5DQ/execute

HTTP headers


Content-type: application/json Openam-Client: {openam_client_id} Openam-Client-Token: {the merchant’s access_token in the integrated with OpenAM application} Paypal-Access-Token: {Paypal access_token}

Payload { "payer_id": "5NTQL5HAA3YAE" }


Expected response

{ "links": [ { "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9PK71013PB057862ULGXZ5DQ",


https://developer.paypal.com/docs/api/payments/#payment_create

https://developer.paypal.com/docs/api/payments/#payment_execute

https://83.235.169.221/


86

"method": "GET", "rel": "self" } ], "payer": { "payment_method": "paypal", "status": "VERIFIED", "payer_info": { "first_name": "test", "last_name": "buyer", "payer_id": "5NTQL5HAA3YAE", "country_code": "US", "shipping_address": { "city": "San Jose", "line1": "1 Main St", "recipient_name": "test buyer", "state": "CA", "postal_code": "95131", "country_code": "US" }, "email": "[email protected]" } }, "transactions": [ { "item_list": { "items": [ { "sku": "1", "name": "Service A", "price": "30.00", "description": " Service A description", "tax": "0.11", "currency": "USD", "quantity": 1 } ], "shipping_address": { "city": "San Jose", "line1": "1 Main St", "recipient_name": "test buyer", "state": "CA", "postal_code": "95131", "country_code": "US" } }, "related_resources": [ { "sale": { "protection_eligibility": "INELIGIBLE", "update_time": "2017-09-06T07:44:03Z", "links": [ { "href": "https://api.sandbox.paypal.com/v1/payments/sale/4FM521024W128042K",



87

"method": "GET", "rel": "self" }, { "href": "https://api.sandbox.paypal.com/v1/payments/sale/4FM521024W128042K/refund", "method": "POST", "rel": "refund" }, { "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9PK71013PB057862ULGXZ5DQ", "method": "GET", "rel": "parent_payment" } ], "reason_code": "PAYMENT_REVIEW", "amount": { "currency": "USD", "total": "30.11", "details": { "shipping_discount": "-1.00", "tax": "0.07", "shipping": "0.03", "handling_fee": "1.00", "subtotal": "30.00", "insurance": "0.01" } }, "id": "4FM521024W128042K", "state": "pending", "create_time": "2017-09-06T07:44:03Z", "payment_mode": "INSTANT_TRANSFER", "parent_payment": "PAY-9PK71013PB057862ULGXZ5DQ", "transaction_fee": { "currency": "USD", "value": "1.17" } } } ], "description": "Sale of service A", "custom": "AoD_90048630024435", "payee": { "merchant_id": "GL2AFHBVU6TXW", "email": "[email protected]" }, "amount": { "currency": "USD", "total": "30.11", "details": { "shipping_discount": "-1.00", "tax": "0.07", "shipping": "0.03", "handling_fee": "1.00",



88

"subtotal": "30.00", "insurance": "0.01" } } } ], "cart": "4KJ62557F0057161B", "state": "approved", "create_time": "2017-09-06T07:44:04Z", "intent": "sale", "id": "PAY-9PK71013PB057862ULGXZ5DQ" }

The payment flow consists of three steps. When the service consumer presses the Buy now button, the P4A application creates the payment. Then, the consumer’s browser is redirected to the approval_url that is included in the response of the web. Figure 50 displays the Paypal login page

while Figure 51 displays the review of the payment; a consumer may approve it by pressing the Continue button or cancel it by pressing the button Cancel and return to APP.

Figure 50: Consumer enters his Paypal credentials after redirection

The button Continue invokes the return_url included in the payload of the web service that creates a payment. This call must invoke the execution of the payment, namely, the service that is described in Table 12. This step will complete the payment. Therefore, the return_url can be an endpoint that triggers the web service that executes the payment. On the other hand, the button Cancel and return to APP invokes the cancel_url included, also, in the payload of the web service that creates a payment.



89

Figure 51: Consumer reviews the service in Paypal.

It’s worth to mention that the endpoints return_url and cancel_url are part of the P4A application, neither the Paypal nor the Payment API.

9.2.4 Create and execute a reccuring payment through Payment API

The Payment API provides a web service that creates a billing plan for a recurring credit card or PayPal payment for services. A billing plan includes payment definitions and other details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each definition determines how often and for how long a consumer is charged. A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles. The plan also defines service provider preferences including how much it costs to set up the agreement, the URLs where a consumer can approve or can cancel the agreement, and the action(s) to be carried out if the consumer 's initial payment fails.

Table 13: P4A Application creates a billing plan on behalf of the service provider

HTTP method POST

Endpoint https://83.235.169.221:443/api/v1/payments/billing-plans

HTTP headers



Openam-Client: {the client_id of application in IAM/OpenAM} Openam-Client-Token: {the merchant’s access_token in the integrated with OpenAM application} Paypal-Access-Token: {Paypal access_token}

Payload

{ "name": "Plan for the Service A", "description": "Plan with Regular payment type", "type": "Fixed", "payment_definitions": [


https://83.235.169.221/


90

{ "name": "Regular Payment Definition", "type": "REGULAR", "frequency": "DAY", "frequency_interval": "1", "amount": { "value": 19.9, "currency": "EUR" }, "cycles": "12", "charge_models": [ { "type": "SHIPPING", "amount": { "value": 0.0, "currency": "EUR" } }, { "type": "TAX", "amount": { "value": 0.0, "currency": "EUR" } } ] } ], "merchant_preferences": { "setup_fee": { "value": 0.0, "currency": "EUR" }, "return_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/execute", "cancel_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/skip", "auto_bill_amount": "YES", "initial_fail_amount_action": "CONTINUE", "max_fail_attempts": "0" } }


Expected response

{ "id": 1, "plan": { "update_time": "2017-09-07T09:56:31.682Z", "name": "Plan for the service Service A", "links": [ { "href": "api.sandbox.paypal.com/v1/payments/billing-plans/P-9EJ7312346482071PLPCOP3A", "method": "GET", "rel": "self" } ], "payment_definitions": [ { "charge_models": [ {



91

"amount": { "currency": "EUR", "value": "0" }, "type": "TAX", "id": "CHM-6EE17563VK9434833LPCOP3A" }, { "amount": { "currency": "EUR", "value": "0" }, "type": "SHIPPING", "id": "CHM-26U06678K4693864PLPCOP3A" } ], "name": "Regular Payment Definition", "frequency_interval": "1", "amount": { "currency": "EUR", "value": "19.9" }, "frequency": "Day", "cycles": "12", "type": "REGULAR", "id": "PD-8YY203668X904832TLPCOP3A" } ], "state": " CREATED", "create_time": "2017-09-07T09:56:24.684Z", "merchant_preferences": { "initial_fail_amount_action": "CONTINUE", "cancel_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/skip", "setup_fee": { "currency": "EUR", "value": "0" }, "auto_bill_amount": "YES", "max_fail_attempts": "0", "return_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/execute" }, "type": "FIXED", "id": "P-9EJ7312346482071PLPCOP3A", "description": "Plan with Regular payment type" } }

The web service above creates a new billing plan for a specific service. This plan consists of one payment definition, the REGULAR one. Thus, any consumer that agrees with this plan will pay 19.9 € every 1 day for a period of 12 days. The frequency of the payment definition could be (1) Day, (2) Week, (3) Month and (4) Year, while the frequency_interval defines the interval at which the consumer is charged (value can’t be greater than 12 months). The cycles attribute defines the



92

number of the payment cycles. This web service is a wrapper of the corresponding Paypal REST web service that creates a billing plan. Further details are available at the link https://developer.paypal.com/docs/api/payments.billing-plans#plan_create.

A further step is required in order to complete the agreement process among service provider and consumer. The activation of an existing plan is achieved by invoking the web service that is described in Table 14. This web service is a wrapper of the corresponding Paypal REST API that activates a billing plan. Further details are available in the link https://developer.paypal.com/docs/api/payments.billing-plans#plan_update.

Table 14: P4A Application activates an existing billing plan on behalf of the service provider

HTTP method PATCH

Endpoint https://83.235.169.221:443/api/v1/payments/billing-plans/{plan-id}

HTTP headers




Payload -


Expected response -

Therefore, assignment of the payment options to the service consists of three steps: 1) service registration in P4A application, 2) creation of the service‘s billing plan and 3) activation of the service’s billing plan. From the consumer perspective, he/she needs to confirm his/her agreement with the billing plan. The Paypal API provides a web service that creates a billing agreement among the service provider and consumer by given service (see Table 15). This web service is a wrapper of the corresponding Paypal web service that is described in the link https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_create.

Table 15: Create a billing agreement for recurring payment among service provider and consumer

HTTP method POST

Endpoint https://83.235.169.221:443/api/v1/payments/billing-agreements

HTTP headers




Payload { "payer": { "payment_method": "paypal"


https://developer.paypal.com/docs/api/payments.billing-plans#plan_create

https://developer.paypal.com/docs/api/payments.billing-plans#plan_update

https://83.235.169.221/

https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_create

https://83.235.169.221/


93

}, "description": "Agreement for Service A of the Panagiotis Athanasoulis", "plan": { "id": "P-9EJ7312346482071PLPCOP3A" }, "name": "Service plan Agreement", "start_date": "2017-09-08T08:31:48Z" }


Expected response

{ "id": 6, "agreement": { "links": [ { "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-2XS95799YH831203L", "method": "REDIRECT", "rel": "approval_url" }, { "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-2XS95799YH831203L/agreement-execute", "method": "POST", "rel": "execute" } ], "description": "Agreement for Service A of the Panagiotis Athanasoulis", "plan": { "description": "Plan with Regular payment type", "payment_definitions": [ { "charge_models": [ { "amount": { "currency": "EUR", "value": "0" }, "type": "TAX", "id": "CHM-6EE17563VK9434833LPCOP3A" }, { "amount": { "currency": "EUR", "value": "0" }, "type": "SHIPPING", "id": "CHM-26U06678K4693864PLPCOP3A" } ], "name": "Regular Payment Definition", "type": "REGULAR", "amount": { "currency": "EUR",



94

"value": "19.9" }, "frequency": "Day", "cycles": "12", "frequency_interval": "1", "id": "PD-8YY203668X904832TLPCOP3A" } ], "state": "ACTIVE", "merchant_preferences": { "initial_fail_amount_action": "CONTINUE", "cancel_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/skip", "setup_fee": { "currency": "EUR", "value": "0" }, "auto_bill_amount": "YES", "max_fail_attempts": "0", "return_url": "http://83.235.169.221:8025/en/services/12/billing-agreement/execute" }, "type": "FIXED", "id": "P-9EJ7312346482071PLPCOP3A", "name": "Plan for the service Service A" }, "name": "Service plan Agreement", "start_date": "2017-09-08T08:31:48Z" } }

After the generation of the billing agreement between two participants, its execution should be performed using the web service described in Table 16. This web service is a wrapper of the corresponding web service of Paypal (https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_execute). The payment_token is included in the response of the web service in Table 9.

Table 16: Activate the billing agreement related to a recurring payment after consumer‘s approval

HTTP method POST

Endpoint https://83.235.169.221:443/api/v1/payments/billing-agreements/{payment_token}/agreement-execute

HTTP headers




Payload -


Expected response {


https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_execute

https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_execute

https://83.235.169.221/


95

"id": 6,

"agreement": {

"payer": {

"payment_method": "paypal",

"status": "verified",

"payer_info": {

"first_name": "test",

"last_name": "buyer",

"email": "[email protected]",

"payer_id": "5NTQL5HAA3YAE",

"shipping_address": {

"city": "San Jose",

"line1": "1 Main St",

"recipient_name": "test buyer",

"state": "CA",

"postal_code": "95131",

"country_code": "US"

}

}

},

"links": [

{

"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-NPRKVVW2WM9F",

"method": "GET",

"rel": "self"

}

],

"agreement_details": {

"cycles_remaining": "12",

"next_billing_date": "2017-09-08T10:00:00Z",

"failed_payment_count": "0",

"final_payment_date": "2017-09-19T10:00:00Z",

"cycles_completed": "0",

"outstanding_balance": {

"value": "0.00"

}

},

"id": "I-NPRKVVW2WM9F",

"state": "Active",

"plan": {



96

"merchant_preferences": {

"setup_fee": {

"value": "0.00"

},

"max_fail_attempts": "0",

"auto_bill_amount": "YES"

},

"payment_definitions": [

{

"charge_models": [

{

"amount": {

"value": "0.00"

},

"type": "TAX"

},

{

"amount": {

"value": "0.00"

},

"type": "SHIPPING"

}

],

"type": "REGULAR",

"amount": {

"value": "19.90"

},

"frequency": "Day",

"cycles": "12",

"frequency_interval": "1"

}

],

"links": [],

"currency_code": "EUR"

},

"shipping_address": {

"city": "San Jose",

"line1": "1 Main St",

"recipient_name": "test buyer",

"state": "CA",

"postal_code": "95131",



97

"country_code": "US"

},

"start_date": "2017-09-08T07:00:00Z",

"description": "Agreement for Service A of the Panagiotis Athanasoulis"

}

}

The response of the above service includes the ID of the recurring payment (I-NPRKVVW2WM9F) and the agreement details such as the number of remaining cycles, the number of the completed cycles and the number of the failed payment attempts.

The completion of the recurring payment process consists of three steps and presupposed that the the billing plan of the service has been activated. When the service consumer presses the Subscribe button, the P4A application creates a billing agreement. After the successful creation of the agreement, the consumer’s browser is redirected to the Paypal GUI and the consumer is able to review the agreement; consider the approval_url included in the response of service described in Table 15. By pressing the button Agree and Continue, the Paypal will redirect the consumer‘s browser to the return_url (as defined in the billing plan creation). This redirection invokes the specific Payment web service for the execution of the billing agreement among the consumer and service provider. In case that the consumer presses the button Cancel and return to APP, the Paypal will redirect the consumer‘s browser to the cancel_url (as defined in the billing plan creation).

Figure 52: Consumer reviews the billing agreement of the desired service

The endpoints return_url and cancel_url are part of the P4A application, neither the Paypal nor the Payment API.



98

The consumer who is a subscriber of a specific service is able to cancel his/her recurring payment by invoking directly the Paypal RESTful web service that is described at the link https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_cancel or suspend it using the corresponding Paypal RESTful service that is described at the link https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_suspend. Both actions trigger Paypal to send a notification event to the notification listener (Payment API).

9.3 Register your app in Paypal Since you have an account in Paypal, login on it, browse on the developer area and especially in the Dashboard. There, you need to press the button My Apps & Credentials on the left menu (your browser should be on the URL https://developer.paypal.com/developer/applications/, see Figure 53).


https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_cancel

https://developer.paypal.com/docs/api/payments.billing-agreements#agreement_suspend

https://developer.paypal.com/developer/applications/


99

Figure 53: Browse on your apps in the Paypal developer dashboard.

Figure 54: Register your application in Paypal

Figure 55: Access the Sandbox API credentials of your application

You can register your application by pressing the button Create App and typing the Application name and Sandbox developer account as seen in Figure 54. After the registration action, you can access



100

and manage the credentials of your application; client ID and Secret. Furthermore, you can setup a sandbox webhook via the Paypal form (notification listener).

Be sure that your application is on sandbox mode to be avoided unwanted charges during the development and testing process.


Documents

D201.5 Prototypes for Architecture, Security, Payment ... · OpenAM API) ... and specialized knowledge required to find, integrate, secure, monetize, and sustain innovative new applications