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 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

AccessToken¶

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¶

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

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

{
    "token_type":   "bearer",
    "access_token": "ac9185e9f2984867b11069fd2881ff1a",
    "expires_in":   3600,
    "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}

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¶

curl --request PUT --url https://api.drop-pay.io/oa2/v1/cc/token
--header Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a

{
  "grant_type": "refresh_token",
  "client_id": "70daac494c7847dba33725b075608cc0",
  "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
  "scope": "app",
  "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}

Response 200¶

{
    "token_type":   "bearer",
    "access_token": "23544dfdf9bd46eaa4a5c88e67559999",
    "expires_in":   3600,
    "refresh_token":"a06c0be7d64b435f975e644b06582345"
}

DELETE - Delete an Application Access Token¶

Example¶

Request¶

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 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

AccessToken¶

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¶

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

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

{
    "token_type":   "bearer",
    "access_token": "ac9185e9f2984867b11069fd2881ff1a",
    "expires_in":   3600,
    "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}

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¶

curl --request PUT --url https://api.drop-pay.io/oa2/v1/ac/token
--header Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a

{
  "grant_type": "refresh_token",
  "client_id": "70daac494c7847dba33725b075608cc0",
  "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
  "scope": "app",
  "refresh_token": "0b78c87d136044c79e3328caf5d66158"
}

Response 200¶

{
    "token_type":   "bearer",
    "access_token": "23544dfdf9bd46eaa4a5c88e67559999",
    "expires_in":   3600,
    "refresh_token":"a06c0be7d64b435f975e644b06582345"
}

DELETE - Delete an User Access Token¶

Example¶

Request¶

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.

See DropPay Common Errors for details about global common errors.