DropPay Security Model¶

When you're developing an application on top of an API like DropPay's, it's really important to get familiar with its security model.

The Actions your application is going to perform on resources, creating, modifying or deleting them, are potentially very dangerous, or, however, they don't lack of risky consequences.

DropPay presents quite a straightforward security model, mainly based on OAuth2 where our mobile application plays a starring role as secure factor of our Strong Authentication paradigm.

Actors and Roles¶

Applications, Application Owners, Account Owners, Developers, a lot of actors are staging the big play and relate each other when an application starts running.

Some useful definition follows:

1. DropPay User: a person who has installed the DropPay mobile app and subscribed at least one account;
2. DropPay Account: valid payment account in the ledger of A-Tono Payment Institution S.p.A. At the time being Personal and Business account commercial type exist;
3. DropPay Application: essentially a couple of credentials that allow a software program to be identified and authorized in accessing DropPay API;
4. Application Owner: a DropPay Business Account Owner who has registered an application and that should keep its credentials safe;
5. Application Developer: who is involved in Application designing, building and deploy.¹ He can eventually coincide with Application Owner.

Applications and Account Owners¶

Applications are built on top of DropPay API to add features and value to DropPay available services.

Application can run requests on behalf of any Account Owner against his own resources, but between them a Connection must be established to make that possible.

Connection is an user explicitly confirmed operation initiated by your app and requires the account owner authorizes DropPay to finalize it.

For instance, if you're building a mobile app that extends DropPay services for Account Owners, your app won't be able to access account data until their owner won't have allowed it.

If Application's and Account's owner are the same DropPay user, a Connection procedure can be initiated from within secure.drop-pay.com Developer Secure Area.

For instance you're deploying your own e-commerce site which is using POS API to allow consumers to choose DropPay as payment scheme.

Usually Application Owner and Account Owner are not the same DropPay User as long as Application Owner is going to act as a provider which delivers a value added service to Account Owners on top of DropPay API. In this case Application Owner will ask Account Owner to establish a Connection between app and account to let the former's application be able to consume API on behalf of Account Owner.

Application Owners and Team Developers¶

Often Application Owners engage software developers to design, develop and deploy new projects and applications.

If you are an Application Owner DropPay allows you to invite collaborators and enable them to manage Application Credentials without needing to know your own personal and secret DropPay Account credentials.

We call this kind of collaborators, Team Developers.

Access Tokens¶

Access Tokens are required to perform any request against DropPay API and must be obtained using Application and User credentials.

When Application are registered in the Developer Secure Area of DropPay website, it comes with a couple of credentials:

• Application Key: a public identifier of your application, the OAuth2 client id;
• Application Secret: a private string to be used as client secret in OAuth2

Access Tokens come in two fashions:

1. Client credentials tokens: must be obtained to call APIs that don't need to access account owner's resources (for example to initiate a new Connection)
2. Connection tokens: must be obtained using the Connection Code (read the next section about it) resulting from a previously established Connection. They are required for all the API calls that involve Account Owner's resources.

Usually the client credential token must be cought only to perform a new Connection (or to access general service status monitoring APIs), but since then only connection tokens are exchanged in "every day" operations.

DropPay Connection¶

A Connection is an explicit, persistent relation between an Application and a single DropPay Account.

When a Connection is created a unique Connection Code is issued.

The Connection Code can be seen as a secret credential an Account Owner reserves to a particular application while his own credentials are kept safe and secret.

When an Application wants to authenticate a request must use the received Connection Code to obtain an temporary connection access token.

In every moment an Account Owner can delete the Connection, so that the Connection Code becomes unusable. We say he revokes the Connection. Since that moment on any attempts Application will make to call API on behalf of that Account Owner will result in a failure unauthorized request.

To get in deep in technical details please read Connection v.1 API Reference.

DropPay Permissions¶

Permissions are requested by DropPay Applications when, acting on behalf of the user whose DropPay Account they are connected to, they need to perform service operations that must be explicitly confirmed by Account owner himself.

Permissions' properties and limits are DropPay Service specific and vary in accordance with Service features, but at most you'll find they will be related to expiration, repeatability and thresholds.

For example an application may request a Permission to be able to transfer money through a SEPA SCT form your DropPay Account toward an IBAN identified recipient.

Granted Permission can be several, also related to same granted Application. They can be revoked or updated by user in any moment.

Permission stand between Applications and Account Owners.

DropPay Authorizations¶

Authorizations are requested by a DropPay Account Owner to another Account Owner in order to be able to perform service operations that involve an asset exchange between them.

Authorizations' properties and limits are DropPay Service specific and vary in accordance with Service features, but at most you'll find they will be related to expiration, repeatability and thresholds.

For example a merchant may request an Authorization to be able to charge a DropPay Account (we call it POS Authorization) after a purchase.

Granted Authorizations can be several, also related to same granted counterparty. They can be revoked but not modified by user in any moment.

Authorizations stand between two Account Owners.

The Disposition Flow¶

Every operation that is eligible to be "user explicitly confirmed" implies to be executed inside what DropPay calls a Disposition Flow. A through the following points:

1. an operation is made available to user acceptance by an external application;
2. user explicitly "imports" the operation in his DropPay mobile app scanning a QR code, tapping on a deeplink or a special push notification.
3. after the acceptance the control is returned to calling application along with data useful to determine the status of the challenge.

One of the most important Operations is the Connection, the procedure by which an Application and a DropPay Account Owner link together statically. Specific Permissions and Authorizations are granted with the Disposition Flow as well.