Skip to content

DropPay API - Connection v.1

The Connection represents the first step an application must perform to be able to effectively use DropPay API against a DropPay account.

The Connection can be considered as a persistent permission granted by a DropPay Account owner to an Application in order to let it "login" DropPay services on behalf of him.

It's persistent but it can be revoked.

The Developer receives a connection_code as user's credential and must keep it safe and secure.

The Connection flow, from the application point of view requires the developer to take care of:

  1. acquire an Application Access Token to authenticate the Connection API request
  2. asking to DropPay API to create a Connection entity;
  3. inviting the user to scan a QR code or hit/tap a deeplink;
  4. acquiring the connection_code and using it to acquire the OAuth2 Access Token.

Connect once

Those steps must be performed whenever your Application needs to obtain a new Connection. Once its connection_code has been saved and until it remains valid you don't need to run the flow anymore.

Asking user to connect (the connection engagement)

DropPay wants a Connection is explicitly acquired by a DropPay account owner using his own mobile app. DropPay Connection API offers you a simple way to accomplish this task by embedding a deeplink (we call it sharing link) like the following one:

https://dp.link/u/20/CONK312VB67

  1. as a link itself
  2. in a button
    PDP
  3. in a QR code
    QR

User will always connect your application by confirming it safely and securely through DropPay mobile app.

The Connection Code

The Connection Code plays exactly the same role of authorization_code parameter in the well-known OAuth2 Authorization Code flow: it enables your application to request an Access Token that authenticates your API calls as they were performed by resource owner himself.

Owner of both Application and DropPay Account

It can happened you have registered a new application to make it work with your own DropPay Account. You can obtain the Connection Code in the Developer Area along with the Application Credentials.

Authenticate your Application: get the Application Access Token

As long as your Application needs a Connection to gain the resource's access as its owner, the Connection comes before the real operations your Application is performing against the User's Account.

In order to consume APIs on behalf of DropPay Users your Application must acquire a User Access Token, but Connection are not initiated by a User, but by the Application itself.

For security reasons DropPay required your Application to "login" before request a new Connection.

See Authentication v.1 API Reference at the section Application Access Token to know how to do it.

Acquiring the Connection Code

Once DropPay user has endorsed the connection you POSTed, there are two way DropPay is trasferring the result and the control back to your application:

  1. POSTing the whole Connection entity to your webhook
  2. Redirecting the user experience completed in DropPay mobile app, to your website or mobile app at URI in loopback_uri

Both are optional, but if you are going to set up anyone of them, you will have to retrieve the Authorization's status polling that with an explicitly request anytime later.

  • webhook is a server URL on HTTP(S)
  • loopback_uri is either an HTTP(S) or a custom schema URI like yourapp://... where arguments are passed in query-string.

At the latter URI DropPay will append two new arguments:

1
    https://yourapplication.com/?a=1&b=2&dps=1&dpcon=CONQA34B31FJ9
  1. dps==: DropPay Status. It can be1or0` in case of success or failure respectively
  2. dpcon==: DropPay Connection ID. This enables your app toGETthecorresponding connection entity and obtain theconnection_code` for the following access request.

Gain access as DropPay Account Owner

Now that you have grabbed the connection_code you can request an access token to make your application do her job with DropPay Account Owner'r resources. See Authentication v.1 API Reference for further details.


REST Entities

Every REST entity is described listing her properties with the following formatting conventions:

  • this is a property name
  • this is a property value
  • (type, returned) is the type of a returned property
  • (type, posted) is the type of a requested property
  • after "-" there's a description

name: example_value - (type, direction) - Property description

Connection
  • id: CONQA34B31FJ9 (string, returned) - Connection resource unique ID
  • application {} (Application, returned) - JSON of connecting Application; see the corresponding Application REST Entity
  • code: ac9185e9f29adf7238fkj9fd2881ff1a (string, returned) - Connection Code to be used as authorization code and obtain the OAuth2 Access Token
  • date_start: 2016-07-16T19:20:30+01:00 (string, returned) - Connection creation date/time. Format ISO-8061
  • date_start: 2016-07-16T19:20:30+01:00 (string, returned) - Connection creation date/time. Format ISO-8061
  • date_last_update: 2016-07-16T19:20:30+01:00 (string, returned) - Connection last update date/time. Format ISO-8061
  • status: WAITING (string, returned) - Status label, one of [WAITING, REFUSED, GRANTED, REVOKED, CANCELLED, EXPIRED] - REFUSED, GRANTED and REVOKED are states the procedure can be moved to by user's action performed in the DroPay mobile app. WAITING and CANCELLED are the initial state of the procedure, just after the creation by the calling app. EXPIRED is set by the system when it can state the procedure has run out the waiting time.
  • webhooks: {} (WebHooks, posted) - URL DropPay will post the Connection object to after user's confirmation. Accept HTTP,HTTPS and optionally basic authentication
  • loopback_uri: https://merchant.com/?a=1&b=2&... (string, posted) - Urlencoded URI used by DropPay mobile app to drive user back to calling app. It can be in HTTP schema or in a custom schema like yourapp://.... Will be appended with connection id that is containing the Connection's code value.
  • sharing: https://dp.link/u/10/CHTQA45B7PA8 (string, returned) - Sharing link to be shown up to make user acquire the connections request with DropPay mobile app

Webhooks

Webhooks

  • all: an URL you provide that is enabled to receive a POST with the updated Connection json payload

Add a webhook property as show below.

1
2
3
    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },

Port 443 allowed only (HTTPS)

Please remember that only secure HTTPS on well-known port 443 webhooks are allowed DropPay doesn't validate webhooks URL, but you won't receive any notification event.

Application
  • *key*: 1ac82ddbb101457dba8b727149b79aef (string, returned) - App key (UUID) to be used as client_id in OAuth2 flows.|
  • *name*: My App (string, returned) - Commercial application's name|
  • *description*: My App is mine. Don't mine what is mine or you'll find a mine. (string, returned) - Extended description of the app (max 512 chars)|
  • *icon*: https://my.app.com/icon.jpg (string, posted, optional) - App's icon (URL)|

REST Endpoints

DropPay Connection publishes three methods :

  • POST a new Connection entity to ask DropPay user to authorize your app
  • GET the Connection entity to read the connection status;
  • DELETE the Connection entity to cancel a just connection still not granted;

Security

Requests must be authenticated with Application Access Token

Details at Authentication v.1 API Reference

Webhooks & Events

Your Application can subscribe to the following webhooks

Webhooks

  • ALL : an URL you provide that is enabled to receive a POST with the updated Connection json payload

Add a webhook property as show below.

1
2
3
    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },

Events

Connection Status Update
1
2
3
4
5
{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "connection.status_update",
    "edata": { A Connection entity }
}

POST Start a Connection challenge procedure

Example

⬆️ Request
1
2
curl --request POST
--url https://api.drop-pay.io/oa2/v1/connection
1
2
3
4
5
6
7
{

    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },
    "loopback_uri": "https://application.com/?a=1&b=2&...",
}
⬇️ Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "id": "CONQA34B31FJ9",
    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },
    "loopback_uri": "https://application.com/?a=1&b=2&...",
    "sharing": "https://dp.link/u/10/CHTQA45B7PA98",
    "status":"WAITING",
    "date_start": "2016-07-16T19:20:30+01:00",
    "application":
    {
        "key": "70daac494c7847dba33725b075608cc0"
    }
}

GET Retrieve a Connection

Example

⬆️ Request
1
2
3
curl --request GET
--url https://api.drop-pay.io/oa2/v1/connection/CONQA34B31FJ9
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
⬇️ Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "id": "CONQA34B31FJ9",
    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },
    "loopback_uri": "https://application.com/?a=1&b=2&...",
    "sharing": "https://dp.link/u/10/CHTQA45B7PA98",
    "status":"GRANTED",
    "date_start": "2016-07-16T19:20:30+01:00",
    "date_last_update": "2016-07-16T19:23:30+01:00",
    "application": {
        "key": "70daac494c7847dba33725b075608cc0"
    }

}

DELETE Cancel a WAITING Connection

Example

⬆️ Request
1
2
3
curl --request DELETE
--url https://api.drop-pay.io/oa2/v1/connection/CONQA34B31FJ9
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
⬇️ Response 204

Errors handling

DropPay POS API is built around REST paradigm so HTTP Status code are consistently informing about what happened running your request.

See DropPay Common Errors for details about global common errors.