Skip to content

DropPay API - Shop v.1 - POS - Devices - Application

Create, update and delete a POS Device of type Application, when is your Application itself to work as a POS Device on top of DropPay POS API.

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

POS

Properties

  • id: POS12JY6DS8 (string, returned) - POS's DropPay public ID
  • status: ENABLED (string, returned) - Status label, one of [ENABLED, DISABLED]
  • device: (Device, returned) - Device object data

POS Device

Properties

  • type: APP (fixed string, returned) - Type name of the POS Device
  • ref: 0385a889-03b2-4bac-ac5e-710042b2ba27 (string, returned) - Your Application Key
  • name: my Application name (string, returned) - Your Application name
  • description: Toons since XIX century (string, returned) - Your Application description

Brand

Properties

  • id: BRNC8K195PZ1Q (string, returned) - Brand's DropPay public ID
  • name: Acme Super Toons (string, returned) - Merchant brand name
  • image: http://acme.server/acmesupertoons.png (string, returned) - Merchant brand logo
  • description: Toons since XIX century (string, returned) - Merchant brand description or payoff
  • business_categories: (array of strings, returned) - Business Categories that characterized products and services offered by the merchant brand. For forthcoming use, now still unuseful
  • payable_account:ACC32123FHS8V (string, returned) - Business Account DropPay public ID. For forthcoming use, now still unuseful
  • status: ENABLED (string, returned) - Status label, one of [ENABLED, DISABLED]
  • stores: (array of Store, returned) - array of Store objects containing merchant store data

Store

Properties

  • id: STRX88DHT129M (string, returned) - Store's DropPay public ID
  • name: Rome Store 1 (string, returned, optional) - Short name of the Store
  • place: REAL (string, returned) - Define is the Store is place to step in or to look at (i.e. adv display) or a virtual place to be visited/read/viewed. Cab be one of [REAL, VIRTUAL].
  • address: Piazza della rotonda - 00186 (string, returned) - Street Address if place is REAL or any other string with the same meaning if place is VIRTUAL (web address, magazines, etc.)
  • georef: (GeoReference, returned, optional) - If place is REAL also georef is present.

GeoReference

Properties

  • lat: 41.8922566 (string, returned) - latitude
  • lon: 12.476499 (string, returned) - longitude

REST Endpoints

DropPay POS API publishes two methods :

  • POST a new POS object entity to set your Application act as POS Device.
  • GET the POS object entity to read the POS Configuration data;
  • PATCH the POS with updated values of allowed properties
  • DELETE a POS (object entity won't be destroyed and it will retain valid referenced info for transactions' history )

Security

Requests must be authenticated with User Access Token

Details at Authentication v.1 API Reference

POST - Make your Application a POS Device

Example

⬆️ Request
1
2
3
4
curl --request POST
--url https://api.drop-pay.io/shop/v1/brand/BRNC8K195PZ1Q/store/STRX88DHT129M/pos
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'Content-Type: application/json'
URL Parameters
1
    /brand/{brand_id}/store/{store_id}/pos
  • brand_id: BRNC8K195PZ1Q (string, required)
  • store_id: STRX88DHT129M (string, required)
Request Body
1
2
3
4
5
6
{
    "device": {
        "type":"APP",
        "ref": "0385a889-03b2-4bac-ac5e-710042b2ba27"
    }
}
⬇️ Response

Returns a POS object like

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "id": "POS12JY6DS8",
    "status": "ENABLED",
    "device": {
        "type": "APP",
        "ref": "0385a889-03b2-4bac-ac5e-710042b2ba27",
        "name": "my Application name",
        "description": "my Application description"
    },
    "brand": {
        "id": "BRNC8K195PZ1Q",
        "status": "ENABLED",
        "name": "Acme Super Toons",
        "logo": "http://acme.server/acmesupertoons.png",
        "description": "Toons since XIX century",
        "business_categories": [
          1,12,19
        ],
        "payable_account": "ACC32123FHS8V",
    },

    "store": {
        "id": "STRX88DHT129M",
        "status": "ENABLED",
        "name": "Rome Store 1",
        "place": "REAL",
        "address": "Piazza della rotonda - 00186",
        "georef" : {
          "lat": 41.8922566,
          "lon": 12.476499
        }
    }
}

GET - Retrieve a POS

Example

⬆️ Request
1
2
3
4
curl --request GET
--url https://api.drop-pay.io/shop/v1/brand/BRNC8K195PZ1Q/store/STRX88DHT129M/pos/POS12JY6DS8
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'Content-Type: application/x-www-form-urlencoded'
URL Parameters
1
    /brand/{brand_id}/store/{store_id}/pos/{pos_id}
  • brand_id: BRNC8K195PZ1Q (string, required)
  • store_id: STRX88DHT129M (string, required)
  • pos_id: POS12JY6DS8 (string, required)
⬇️ Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "id": "POS12JY6DS8",
    "status": "ENABLED",
    "device": {
        "type": "APP",
        "ref": "0385a889-03b2-4bac-ac5e-710042b2ba27",
        "name": "my Application name",
        "description": "my Application description"
    },
    "brand": {
        "id": "BRNC8K195PZ1Q",
        "status": "ENABLED",
        "name": "Acme Super Toons",
        "logo": "http://acme.server/acmesupertoons.png",
        "description": "Toons since XIX century",
        "business_categories": [
          1,12,19
        ],
        "payable_account": "ACC32123FHS8V",
    },

    "store": {
        "id": "STRX88DHT129M",
        "status": "ENABLED",
        "name": "Rome Store 1",
        "place": "REAL",
        "address": "Piazza della rotonda - 00186",
        "georef" : {
          "lat": 41.8922566,
          "lon": 12.476499
        }
    }
}

PATCH - Update POS properties

Example

⬆️ Request
1
2
3
4
curl --request PATCH
--url https://api.drop-pay.io/shop/v1/brand/BRNC8K195PZ1Q/store/STRX88DHT129M/pos/POS12JY6DS8
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'Content-Type: application/json'
URL Parameters
1
    /brand/{brand_id}/store/{store_id}/pos/{pos_id}
  • brand_id: BRNC8K195PZ1Q (string, required)
  • store_id: STRX88DHT129M (string, required)
  • pos_id: POS12JY6DS8 (string, required)
Request Body

Here we disable the POS and we change the Application Key. What we want to do is putting POS is temporarely out of order, for maintenance, and changing Application, while preserving all POS historical activity and setting it ready to be restored without loosing business data.

One Application, multiple POS

Remember that a single Application (identified by an Application Key) can acts as POS in multiple Stores as long as you just need to set the correct pos_id every time a new Authorization is POSTed.

1
2
3
4
5
6
7
{
    "status": "DISABLED",
    "device": {
        "type":"APP",
        "ref": "af6cfd85-9021-42e9-8096-bd60d68fe3e2"
    }
}
⬇️ Response

Returns a POS object like

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "id": "POS12JY6DS8",
    "status": "DISABLED",
    "device": {
        "type": "APP",
        "ref": "af6cfd85-9021-42e9-8096-bd60d68fe3e2",
        "name": "my new Application name",
        "description": "my new Application description"
    },
    "brand": {
        "id": "BRNC8K195PZ1Q",
        "status": "ENABLED",
        "name": "Acme Super Toons",
        "logo": "http://acme.server/acmesupertoons.png",
        "description": "Toons since XIX century",
        "business_categories": [
          1,12,19
        ],
        "payable_account": "ACC32123FHS8V",
    },

    "store": {
        "id": "STRX88DHT129M",
        "status": "ENABLED",
        "name": "Rome Store 1",
        "place": "REAL",
        "address": "Piazza della rotonda - 00186",
        "georef" : {
          "lat": 41.8922566,
          "lon": 12.476499
        }
    }
}

DELETE - Delete a POS

POS object entity deletion is not physical. Transaction history won't be affected.

Example

⬆️ Request
1
2
3
4
curl --request DELETE
--url https://api.drop-pay.io/shop/v1/brand/BRNC8K195PZ1Q/store/STRX88DHT129M/pos/POS12JY6DS8
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'Content-Type: application/x-www-form-urlencoded'
URL Parameters
1
    /brand/{brand_id}/store/{store_id}/pos/{pos_id}
  • brand_id: BRNC8K195PZ1Q (string, required)
  • store_id: STRX88DHT129M (string, required)
  • pos_id: POS12JY6DS8 (string, required)
⬇️ 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.