Skip to content

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

  1. as a link itself
  2. in a button
    PDP
  3. in a QR code
    QR

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