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

Authorization
  • id: CHTQA45B7PA98 (string, returned) - Unique ID of the resource
  • scheme: CREDIT (string, posted/returned, optional) - Payment scheme identifier. One of [CREDIT]
  • scheme_data (object, posted/returned, optional) - Object entity according to selected Payment Scheme
  • pos_id: POS12562I3HG (string, posted/returned) - Merchant DropPay POS unique identifier
  • date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - Creation date/time of the resource. Format ISO-8061
  • date_last_update: 2016-07-16T19:20:30+01:00 (string, returned) - Last update date/time. Format ISO-8061
  • status: GRANTED (string, returned) - Status label, one of [WAITING, GRANTED, EXPIRED, REVOKED, REFUSED, CANCELLED]
  • description: Your filled cart (string, posted) - Good or service description, max 512 chars
  • charge_amount: 50.00 (number, posted) - Amount of the single charge will be performed (DropPay supports only Euro currency)
  • charge_max_count: 1 (number, returned) - Maximum amount of charge operation allowed by this Authorization. Fixed to 1.
  • charge_success_count: 1 (number, returned) - Amount of authorized charges successfully completed. Fixed to 1.
  • merchant_custom_id: 13412ga723f94t02ncbcv9sf9h (string, posted) - Custom identifier set by merchant.
  • merchant_custom_label: cart-13412ga723f94t02ncbcv9sf9h (string, posted) - Custom identifier set by merchant.
  • merchant_business_name: ACME Ltd. (string, returned) - ragione sociale del merchant titolare del brand
  • webhooks: (Webhooks, posted) - URL DropPay will post the authorization object to after user's confirmation. Accept HTTP,HTTPS and optionally basic authentication
  • brand: (Brand, returned) - Brand structure containing merchant brand data
  • store: (Store, returned) - Store structure containing merchant store data
  • policy: CHARGED (string, posted) - Switch to control authorization policy to be applied to authorization. Fixed to CHARGED.
Brand
  • id: BRNC8K195PZ1Q (string, required, returned) - Brand's DropPay public ID
  • name: Acme Super Toons (string, required, returned) - Merchant brand name
  • image: http://acme.server/acmesupertoons.png (string, optional,returned) - Merchant brand logo
  • description: Toons since XIX century (string, required, 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) - Arrau of Store objects containing merchant store data
Store
  • 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

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

Webhooks

Properties

  • ALL: https://credenA:credenB@app.server.com/listener (string, optional) - URL the app's developer wants to be notified of user's confirmation of the Authorization

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

Webhooks

  • ALL: an URL you provide that is enabled to receive a POST with the updated Authorization json payload

Add a webhook property as show below.

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

Port 443 allowed only (HTTPS)

Please remember that only secure HTTPS on well-known port 443 webhooks are allowed DropPay doesn't validate webhooks URL, but you won't receive any notification event.

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.

HTTP Error Statuses with ErrorInfo payload

  • Status 400 Bad Request
    • Code 202 Invalid Authorization Policy
  • Status 403 Forbidden
    • Code 200 Payer and payee must be different
  • Status 409 Conflict
    • Code 200 Authorization expired

See DropPay Common Errors for details about global common errors.