DropPay API - Overview¶

The DropPay API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which are understood by off-the-shelf HTTP clients.

DropPay API uses OAuth2 standard flows and parameters to authorize your applications.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Domain¶

Production DropPay API is published at the following domain:

Application and Users Authentication and Authorization¶

An application must exist and be registered in DropPay, under your account, before it can be run to consume the API.

By creating a new app you will receive a couple of credentials

• Application Key
• Application Secret

You can manage your application credentials in the Developer area of your account at https://secure.drop-pay.com.

Connection¶

Once you have obtained the Application credentials, in order to make your application being able to call DropPay services API for any useful task, you must obtain another special credential, the Connection Code.

What really is 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 (User Access Token).

The Connection Code is acquired at the end of the Connection challenge your app must engage with a DropPay user which is asked to approve to connect his DropPay account to your application.

The Connection lets the DropPay user to get all the advantages your application is offering by accessing his account data and preserve his freedom to revoke the grants in whenever he desires to.

Access Tokens¶

With all three the credentials your application can finally request the Access Token to consume the API.

See Authentication v.1 API Reference for details.

Refreshing Tokens¶

DropPay authentication and authorization are compliant with OAuth2 standards, so you can refresh access tokens when they expire without requesting a new one.

See Connection v.1 API Reference for details.

Headers¶

DropPay uses custom headers for special purposes. All headers are prefixed by the string:

Available DropPay headers can be used in requests and can be extract from responses.

Errors¶

DropPay uses conventional HTTP response codes to indicate the success or failure of an API request.

Usually:

• codes in the 2xx range indicate success;
• codes in the 4xx range indicate an error raised by DropPay given the information providedin in the request (e.g., a required parameter was omitted, a charge failed, etc.);
• codes in the 5xx range indicate an error with DropPay's servers.

However not for all statuses the standard mapping onto HTTP codes is sound and complete. In the cases it's not sound we add a custom code in the 2xx,4xx or 5xx space, and the cases it's not complete we include a JSON payload in the response body with additional informations.

A typical Status 400 DropPay detailed response is:

{
    "code":10,
    "description": "Missing arguments"
}

See DropPay Common Errors for details.

Webhooks & Events¶

DropPay API can notify your Application with events raised asynchronously by status changes of relevant resources. For example a Connection has been granted by an User or a payment has been completed and so on.

When API offers one or more webhooks your Application can subscribe an URL to inform DropPay where to push the notifications when the corresponding events occur.

Events are JSON payloads with the structure shown below:

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype":"pos.authorization.status_update",
    "edata": {...}

}

where

• etype is a string that identifies the event
• edata contains the event data describing events of that type
• etime is the event timestamp

Available webhooks and referred events are described in specific API document section of this site.

API Versioning¶

Here below all available API are listed.

Every API comes with a version number and the same version number is part of the base HTTP path where API is available under api.drop-pay.io domain.

Beside each API version a label can inform on its lifecycle status:

• fortcoming YYYY-MM-DD: API is a work in progress and we have planned a release at the visible date
• deprecated YYYY-MM-DD: API is still live but will be shutdown after the visible date
• shutdown YYYY-MM-DD: API has been shutdown at the visible date

Available API¶

• Authentication API v.1
• Connection API v.1
• Shop v.1 / POS API v.1
• Shop v.1 / Checkout v.1

Backward compatibility¶

DropPay adheres the following versioning policies to determine the current release can be kept live:

1. add new API resources.
2. add new optional request parameters to existing API methods.
3. add new properties to existing API responses.

When at least one of those policy has been violated because changes don't actually fit one all of them DropPay will plan a new API version release.