DropPay API - Shop v.1 - Virtual POS Device¶

Acquirer - Authorization¶

Payment authorization (aka Authorization) represents the only step a merchant must go through when informing DropPay a new payment has been performed through an other POS that will exchange the user's payment scheme funds with A-Tono Payment Institute as acquirer.

The Authorization flow, from the merchant's application point of view, wants the developer to take care of:

1. asking DropPay API to create a new Authorization entity with a defined POS

Authorization Policies and use cases¶

DropPay POS API comes with four authorization policies but with Acquirer Virtual POS Device you can you can only take advantage of a unique value of policy property:

1. CHARGED: DropPay condiders the user's account already charged at the same time the authorization is granted.

Authorization counterparties¶

When creating a new authorization your application must act on behalf of the merchant party.

Merchant user must have previously connected his DropPay account (take a look at Connection API reference to get deeper in details) in order to POST a new authorization.

Your application must know the POS ID, while payer User info are optional.

Remember a DropPay business Account owner must have previously * created a Brand on one of his DropPay Business accounts, * connected your application with the same account * linked your app as a POS Device in a Store of the chosen Brand * obtained from A-Tono Payment Institute a POS attached with Virtual POS Device of type Acquirer fully configured with MerchantID and TerminalID needed by real POS Devices to perform initialization and tu run operations.

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

Authorization¶

Brand¶

Store¶

GeoReference¶

Webhooks¶

REST Endpoints¶

DropPay POS API publishes three methods :

• POST a new Authorization entity to start a payment procedure;
• GET the Authorization entity to read the payment status;
• DELETE the Authorization entity to revert the initiated procedure before it is completed by the user.

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

Webhooks & Events¶

Your Application can subscribe to the following webhooks

Add a webhook property as show below.

    "webhooks": {
        "ALL": "https://credenA:credenB@app.server.com/listener"
    },

Events¶

Connection Status Update¶

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "shop.pos.authorization.status_update",
    "edata": { A POS Authorization Status Update },
}

POST - Request a new authorization¶

Example¶

Request¶

  curl --request POST
       --url https://api.drop-pay.io/shop/v1/pos/authorization
       --header 'Authorization: Bearer or872y08472fhcbqc8714pquiwcnbwtwfwc'

{
  "description": "Your filled cart",
  "charge_amount": 50.00,
  "pos_id": "POSV265V3PQ9E",
  "merchant_custom_id" : "cart-13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "XMas2016-campaign",
  "webhooks": {
      "ALL": "https://credenA:credenB@app.server.com/listener"
  },
}

Response 200¶

{
  "id": "CHTQA45B7PA98",
  "description": "Your filled cart",
  "charge_amount": 50.00,
  "charge_date_start": "2016-07-16T19:20:30+01:00",
  "charge_max_count": 1,
  "pos_id": "POSV265V3PQ9E",
  "merchant_custom_id": "cart-13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "XMas2016-campaign",
  "webhooks": {
      "ALL": "https://credenA:credenB@app.server.com/listener"
  },
  "policy": "CHARGED",
  "status": "WAITING"
}

PATCH - Confirm a waiting Authorization¶

Example¶

Request¶

  curl --request PATCH
      --url https://api.drop-pay.io/shop/v1/pos/authorization/CHTQA45B7PA98
      --header 'Authorization: Bearer or872y08472fhcbqc8714pquiwcnbwtwfwc'

{
  "status": "GRANTED"
}

Response 200¶

{
  "id": "CHTQA45B7PA98",
  "description": "Your filled cart",
  "charge_amount": 50.00,
  "charge_date_start": "2016-07-16T19:20:30+01:00",
  "charge_max_count": 1,
  "pos_id": "POSV265V3PQ9E",
  "merchant_custom_id": "cart-13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "XMas2016-campaign",
  "webhooks": {
      "ALL": "https://credenA:credenB@app.server.com/listener"
  },
  "policy": "CHARGED",
  "status": "GRANTED"
}

GET - Retrieve an already created authorization¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/shop/v1/pos/authorization/CHTQA45B7PA98
--header 'Authorization: Bearer or872y08472fhcbqc8714pquiwcnbwtwfwc'

Response 200¶

{
  "id": "CHTQA45B7PA98",
  "description": "Your filled cart",
  "charge_amount": 50.00,
  "charge_date_start": "2016-07-16T19:20:30+01:00",
  "charge_max_count": 1,
  "pos_id": "POSV265V3PQ9E",
  "merchant_custom_id": "cart-13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "XMas2016-campaign",
  "webhooks": {
      "ALL": "https://credenA:credenB@app.server.com/listener"
  },
  "policy": "CHARGED",
  "status": "GRANTED",
  "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_max_count": 1,
 }
}

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.