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.

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:

1. as a link itself
   Connect your DropPay Account
2. in a button
   
3. in a QR code
   

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.

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:

    https://yourapplication.com/?a=1&b=2&dps=1&dpcon=CONQA34B31FJ9

1. dps: DropPay Status. It can be 1 or 0 in case of success or failure respectively
2. dpcon: DropPay Connection ID. This enables your app to GET the corresponding connection entity and obtain the connection_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 an example of property value
• (type, policy, direction) is the specification of a property
  • type can be "string", "number", "object" or a proper object class name
  • policy can be "optional" or "required"
  • direction can be "posted" or "received" depending on whether you set it in the request or you got it from the response
• after the dash "-" there's the property description

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

Connection¶

Webhooks¶

Add a webhook property as show below.

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

Application¶

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

Add a webhook property as show below.

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

Events¶

Connection Status Update¶

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "connection.status_update",
    "edata": { A Connection entity }
}

POST Start a Connection challenge procedure¶

Example¶

Request¶

curl --request POST
--url https://api.drop-pay.io/oa2/v1/connection

{

    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },
    "loopback_uri": "https://application.com/?a=1&b=2&...",
}

Response 200¶

{
    "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¶

curl --request GET
--url https://api.drop-pay.io/oa2/v1/connection/CONQA34B31FJ9
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

Response 200¶

{
    "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¶

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.