Skip to content

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:

https://api.drop-pay.io

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.

Owner of both Application and DropPay Account

It could happen you have registered a new application to make it work with your own DropPay Account. You can obtain the Connection Code starting a challenge procedure from within the Developer Area as it was performed by your application itself. DropPay will iniate the Connection as it was your own Application.

Headers

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

X-DropPay-{HeaderName}

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:

1
2
3
4
{
    "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:

1
2
3
4
5
6
{
    "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

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.