DropPay API¶

Shop v.1¶

Virtual POS Devices - DropPay¶

To use a DropPay POS with a DropPay Virtual POS Device you have to:

Ask user to authorize your payment proposal, by showing a special QR code or a deeplink and get a PayToken in return;
Charge user once you're ready to deliver your service or good using the PayToken until it is active;

and later you can

Refund user up to previously authorized amount of every single charge if something went wrong at delivering time of your service.

Asking user to pay (the payment engagement)¶

DropPay wants a Payment Authorization is explicitly acquired by a DropPay account owner using his own mobile app. DropPay POS API offers you a simple way to accomplish this task by embedding a deep link like the following one:

https://dp.link/u/10/CHTQA45B7PA98

as a link itself
Paga con DropPay
in a button
in a QR code

User will authorize the payment by confirming it safely and securely always through his DropPay mobile app.

What's a DropPay PayToken ?¶

You're receiving a pay_token at the very end of every authorization flow.

A Pay Token represents the real permission granted by user and it's the mandatory property to be passed in when charging user's DropPay account.

Without a valid pay_token charging process will result in a failure.

Here below an example of pay_token is shown.

"pay_token" : {
    "val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
    "date_issued": "2016-07-16T19:20:30+01:00",
    "date_expiring": "2016-07-16T19:20:30+01:00",
    "charge_available": 1,
  }

A pay_tokenis issued at pay_token.date_issued and must be consumed before pay_token.date_expiring.

Pay Token value is refreshing

Every time you read the authorization, until it is valid, the Pay Token is reset to let you charge user's account for a short period of time (180 secs). Conversely, you MUST read the Authorization to obtain a refreshed Pay Token useful for your further actions.

See Authorization API Reference for details also about how to correctly retrieve the pay_token.

Charge users' DropPay account¶

Charging is performed creating a Charge object by passing in the pay_token acquired at the end of authorization procedure.

You can use the pay_token as many times as the corresponding authorization enables you to and until it expires.

If you choose to have user implicitly charged at authorization time (suitable for a single payment), charging attempts will result in a failure and a 403 - FORBIDDEN HTTP response status is returned.

See Charge API Reference for details.

POS and Virtual POS Device¶

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

POS¶

POS

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¶

POS Device

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

{!!API/Shop/_includes/rest-entities-brand-store.md}

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. User Access Token can be obtained requesting it with and active Connection Code.

Details at Authentication v.1 API Reference

POST - Make your Application a POS Device¶

Example¶

Request¶

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¶

    /brand/{brand_id}/store/{store_id}/pos

brand_id: BRNC8K195PZ1Q (string, required)
store_id: STRX88DHT129M (string, required)

Request Body¶

{
    "device": {
        "type":"APP",
        "ref": "0385a889-03b2-4bac-ac5e-710042b2ba27"
    }
}

Response¶

Returns a POS object like

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

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¶

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

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

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¶

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

{
    "status": "DISABLED",
    "device": {
        "type":"APP",
        "ref": "af6cfd85-9021-42e9-8096-bd60d68fe3e2"
    }
}

Response¶

Returns a POS object like

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

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¶

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