Skip to content

DropPay API - Authentication v.1

Authenticating the requests your Application is performing against DropPay API is mandatory.

Authentication is obtained through a valid OAuth2 Access Token obtained by a preliminary token request.

Access Token comes in two fashions :

  1. User Access Tokens: got with OAuth2 Authorization Code flow
  2. Application Access Tokens: got with OAuth2 Client Credential flow

API Docs inform you about what kind of access you must gain as long as access types are API and resource specific.

Application Access

Applications must obtain an OAuth2 Client Credential token when the API they're about to consume are not intended to work on DropPay User owned resources, but require nevertheless that Applications are authenticated and authorized.

DropPay does not export public API.

The following sections are about Application Access Token.

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

AccessToken

AccessToken
  • token_type: bearer - (string, returned)
  • access_token: ac9185e9f2984867b11069fd2881ff1a (string, returned) - OAuth2 access token
  • expires_in: 3600 (number, returned) - Access Token time to live
  • refresh_token: ac9185e9f2984867b11069fd2881ff1a (string, returned) - OAuth2 refresh token

REST Endpoints

DropPay Connection publishes three methods :

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

POST - Request a new Application Access Token

Example
⬆️ Request
1
curl --request POST --url https://api.drop-pay.io/oa2/v1/cc/token
1
2
3
4
5
6
{
    "grant_type": "client_credentials",
    "client_id": "70daac494c7847dba33725b075608cc0",
    "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
    "scope": "app"
}
  • client_id value is the Application Key value
  • client_secret value is the Application Secret value
  • grant_type and scope values are fixed.
⬇️ Response 200

1
2
3
4
5
6
{
    "token_type":   "bearer",
    "access_token": "ac9185e9f2984867b11069fd2881ff1a",
    "expires_in":   3600,
    "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}
Now put the access_token value in the HTTP request header (in example GETting a Connection):

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

DropPay authentication and authorization are regulated by OAuth2 standards, so you can refresh token when it expires without requesting a new one authenticating again.

PUT - Request a refreshed Application Access Token

Example
⬆️ Request
1
2
curl --request PUT --url https://api.drop-pay.io/oa2/v1/cc/token
--header Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a
1
2
3
4
5
6
7
{
  "grant_type": "client_credentials",
  "client_id": "70daac494c7847dba33725b075608cc0",
  "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
  "scope": "app",
  "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}
⬇️ Response 200
1
2
3
4
5
6
{
    "token_type":   "bearer",
    "access_token": "23544dfdf9bd46eaa4a5c88e67559999",
    "expires_in":   3600,
    "refresh_token":"a06c0be7d64b435f975e644b06582345"
}

DELETE - Delete an Application Access Token

Example
⬆️ Request
1
2
curl --request DELETE --url https://api.drop-pay.io/oa2/v1/cc/token
--header Authorization: Bearer 23544dfdf9bd46eaa4a5c88e67559999
⬇️ Response 204

User Access

To authenticate as User and get the User Acess Token your Application must have previously saved a connection_code by which the User, that is an Account Owner has granted, until revoke, the authorization to consume API in behalf of him.

If you are both the Application Owner and DropPay Account owner, so possibly you want to connect your own application (i.e. you're developing your own e-commerce site or shop payment application), then you can obtain the Connection Code initiating the connection flow from within the Developer Secure Area of web app, along with the Application Credentials.

See Connection v.1 API Reference for 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

AccessToken

Properties

  • token_type: bearer - (string, returned)
  • access_token: ac9185e9f2984867b11069fd2881ff1a (string, returned) - OAuth2 access token
  • expires_in: 3600 (number, returned) - Access Token time to live
  • refresh_token: ac9185e9f2984867b11069fd2881ff1a (string, returned) - OAuth2 refresh token

REST Endpoints

DropPay Connection publishes three methods :

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

POST - Request a new User Access Token

Example
⬆️ Request
1
curl --request POST --url https://api.drop-pay.io/oa2/v1/ac/token
1
2
3
4
5
6
7
{
    "grant_type": "authorization_code",
    "code": "ac9185e9f29adf7238fkj9fd2881ff1a",
    "client_id": "70daac494c7847dba33725b075608cc0",
    "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
    "scope": "app"
}
  • code value is Connection Code value
  • client_id value is the Application Key value
  • client_secret value is the Application Secret value
  • grant_type and scope values are fixed.
⬇️ Response 200

1
2
3
4
5
6
{
    "token_type":   "bearer",
    "access_token": "ac9185e9f2984867b11069fd2881ff1a",
    "expires_in":   3600,
    "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}
Now put the access_token value in the HTTP request header:

1
2
3
curl --request GET
--url https://api.drop-pay.io/shop/pos/charge/CHAQA34B31FJ9
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

DropPay authentication and authorization are regulated by OAuth2 standards, so you can refresh token when it expires without requesting a new one authenticating again.

PUT - Request a refreshed User Access Token

Example
⬆️ Request
1
2
curl --request PUT --url https://api.drop-pay.io/oa2/v1/ac/token
--header Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a
1
2
3
4
5
6
7
{
  "grant_type": "authorization_code",
  "client_id": "70daac494c7847dba33725b075608cc0",
  "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
  "scope": "app",
  "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}
⬇️ Response 200
1
2
3
4
5
6
{
    "token_type":   "bearer",
    "access_token": "23544dfdf9bd46eaa4a5c88e67559999",
    "expires_in":   3600,
    "refresh_token":"a06c0be7d64b435f975e644b06582345"
}

DELETE - Delete an User Access Token

Example
⬆️ Request
1
2
curl --request DELETE --url https://api.drop-pay.io/oa2/v1/ac/token
--header Authorization: Bearer 23544dfdf9bd46eaa4a5c88e67559999
⬇️ 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.

Below specific API context errors are listed.

HTTP Error Statuses with ErrorInfo payload

  • Status 401 Unauthorized
    • Code 700 Wrong credentials
  • Status 429 Too many requests
    • Code 700 Too many login attempts Retry-After header value

See DropPay Common Errors for details about global common errors.