DropPay API

Shop v.1

DropPay Virtual POS Device - Authorization

Payment authorization (aka Authorization) represents the first step a merchant must perform when requesting a payment to a DropPay account owner.

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
  2. inviting user to scan a QR code or hit/tap a deeplink
  3. acquiring the pay_token and using it whenever a charge command must be issued

Hint

At the moment you create the Authorization you can also:

  1. force DropPay to charge user's account at the same time. This is performed by setting the policy property : "policy":"CHARGED". DropPay will charge user's account with the Authorization amount;
  2. force DropPay to book user's account balance by a defined amount of credit that is going to be charged later up to booked value. This is performed by setting the policy property : "policy":"BOOKED".

DropPay Pay Token

You're receiving a pay_token at the very end of each successful authorization flow. The Pay Token is the mandatory property to be passed in when charging a DropPay user. Not using a valid pay_token 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 for a maximum of pay_token.charge_available times. pay_token.charge_available should be the difference between authorization.charge_max_count and authorization.charge_success_count (see also Authorization REST entity below).

The pay_token lifetime is limited to about 180 seconds. Every time you GET an Authorization DropPay verifies if the lifetime has expired. If so, and the Authorization itself is still valid, the pay_token lifetime is reset and it becomes newly available for a charge command.

Acquiring the Pay Token (being notified)

Once DropPay user has granted the authorization you POSTed, there are two ways DropPay is transferring the result and the control back to your application:

  1. POSTing the whole Authorization entity to your webhook
  2. Redirecting the user experience completed in DropPay mobile app, to your website or mobile app at URI in loopback_uri

Both are optional, but if you are not setting up anyone of them, you will will have to retrieve the Authorization's status polling that with an explicitly request at anytime later.

  • webhook is a server URL on HTTP(S)
  • loopback_uri is either an HTTP(S) or a custom schema URI like yourapp://... where arguments are passed in query-string.

At the latter URI DropPay will append two new arguments:

    https://merchant.com/back?a=1&b=2&dps=1&dpcht=CHTQA45B7PA98
  1. dps: DropPay Status. It can be 1 or 0 in case of success or failure respectively
  2. dpcht: DropPay Authorization ID. This enables your app to GET the corresponding authorization entity and obtain the pay_token for the next charges.

Pay Token example

"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,
  }

Authorization Policies and use cases

DropPay POS API comes with four authorization policies you can ask user to grant selecting the right label as value of policy property:

  1. CHARGEABLE: this is the default policy, get authorized, charge later;
  2. CHARGED: DropPay charge the user's account at the same time he grant the authorization; Application does not have to charge the amount later;
  3. BOOKABLE: you got an authorization that enables your application to book an amount of user's account balance later and the charge it up to that amount;
  4. BOOKED: you got an authorization to charge the user's account later up to the amount value that DropPay has already booked at granting time.

Forthcoming features

Currently Authorization don't implement the following policy:

  • BOOKABLE

Get authorized, charge later

The pattern used by DropPay in the payment flow separates the authorization procedure from the charge one.

First you get authorized by user, then you decide when actually charge his account. This gives a better control on the exact moment in which DropPay will subtract money from the user's account.

That is quite straightforward even in the case of multiple charges performed with the same authorization.

For example you might want to make the user pays at the early stage of the order to reserve a stock keeping unit and then charge him only at the moment of shipping.

The default behavior of DropPay is not to charge at authorization time.

Get authorized and paid simultaneously

Nevertheless, if you're asking a single payment you can force DropPay to charge user immediately setting the authorizations's property conveniently

{
    "charge_max_count":1,
    "policy":"CHARGED"
}

The CHARGED value of policy is not allowed for multiple charge authorizations.

The pay_token you're receiving back in this case won't be useful because DropPay will have already consumed it.

See also Charge API Reference for further details.

Deferred auto charging

Setting the property charge_date_start with a date in the future, the very first (or the only one) charge will be deferred to that date

  • and automatically enforced by DropPay itself if policy=CHARGED is set as well,
  • or it will be allowed to be charged only after that date if policy=CHARGEABLE is set (default).

See also Charge API Reference for further details.

Booking and charging a final balance

Let's play with an example. Imaging you want to deliver a service or a good by a vending machine and you have to charge consumer only when your machine knows the actual product volume delivered (yes... we're thinking about a fuel self service station or a time based parking service, too).

What you must do is to ask user to authorize a reservation of a maximum defined amount of credit and to charge it later when the real price of the delivered product is fully known.

With DropPay this is as easy as collecting all the other payments. Just challenge your customer with an authorization where

{

    "charge_max_count": 1,
    "charge_amount": 50.00,
    "policy":"BOOKED"
}
50,00€ of user's balance will be reserved (if available).

After you have received the GRANTED Authorization, enable user to spill fuel, fetch contents, listen music, play videos, park his car... or whatever.

At the end of delivery, get the pay_token, set the final price and charge it, taking care you can not exceed the charge_amount valued previously authorized.

But what if can't know the maximum amount to be booked at the time you initiate the authorization procedure ?

Simply set

{
    "policy":"BOOKABLE"
}
and you will authorized to defer booking calling ´book´ API only when you'll need to.

Forthcoming features

Currently Authorization don't implement the following policy:

  • BOOKABLE

and the corresponding useful method /book has not been published yet.

Multiple and Recurring Payments (Authorize once, Charge many)

DropPay enables you to charge user's account several times asking him to authorize just once.

You can request user to grant payments that can be

  1. multiple: charging is up to you
  2. multiple & recurring: charging is scheduled and executed on DropPay

Multiple payments are not necessarily recurring. They could be triggered by specific and asynchronous actions customer is going to perform against your commerce services during a validity period (see charge_date_end property).

User must be informed about how many times you're going to charge setting charge_max_count properly.

Moreover you can manage recurring payments on your own, setting up a scheduler on your side, able to fire up charge events accordingly to your needs, but you can delegate DropPay to take care of this on behalf of you.

See also Charge API Reference for further details.

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 (you will share the payment link resulting from the Authorization creation and the payer will reveal himself just after have imported it by his DropPay mobile app).

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

Forthcoming features

Making an Application a POS of a Store is Currently possibile only through the GUI of Developer Secure Area of DropPay website. This implies that Application Owner must be the same DropPay User as the Brand Owner.

The new authorization you create is going to possibly lack any information about the payer is about to purchase your product.

Don't worry about. Just do it, then present the sharing link value to user (in the overview we show the way to accomplish that task). He will scan the code with DropPay mobile app, identify himself and selecting the account to be debited.

On the other hand, you may ask the consumer to provide you with his DropPay payer.username and/or his payer.iban. This will result in binding the sharing link to that user therefore no one else will be able to pay on his place.


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

Properties

  • id: CHTQA45B7PA98 (string, returned) - Unique ID of the resource
  • scheme: DROPPAY (string, posted/returned, optional) - Payment scheme identifier. One of [DROPPAY,SEPASCT], default DROPPAY
  • scheme_data (object, posted/returned, optional) - Object entity according to selected Payment Scheme
  • 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_date_start: 2016-07-16T19:20:30+01:00 (string, posted) - Date/time after which charge must be accepted. Defaults to now().
  • charge_date_end: 2016-07-16T19:20:30+01:00 (string, posted/returned) - Date/time of authorization's expiration. Format ISO-8061.
  • charge_date_last: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of last executed charge. Format ISO-8061.
  • charge_max_count: 1 (number, posted) - Maximum amount of charge operation allowed by this Authorization. Must be > 0
  • charge_success_count: 1 (number, returned) - Amount of authorized charges successfully completed
  • charge_description: (string, posted) - Used if charge reason narrative is different from authorization one (i.e. "Subscription" vs. "Monthly fee")
  • pos_id: POS12562I3HG (string, posted/returned) - Merchant DropPay Shop unique identifier
  • 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
  • loopback_uri: https://merchant.com/?a=1&b=2&... (string, posted) - Urlencoded URI used by DropPay mobile app to drive user back to calling application. It can be a HTTP schema or a custom schema like yourapp://.... Will be appended with authorization id.
  • brand: (Brand, returned) - Brand structure containing merchant brand data
  • store: (Store, returned) - Store structure containing merchant store data
  • pay_token: (PayToken, returned) - Paytoken object
  • policy: CHARGED (string, posted) - Switch to control authorization policy to be applied to authorization. One of [CHARGEABLE,BOOKABLE,CHARGED,BOOKED].
  • sharing: https://dp.link/u/10/CHTQA45B7PA98 (string, returned) - Sharing link to be shown up to make user acquire the authorization with DropPay mobile app

Brand

Properties

  • name: Acme Super Toons (string, returned) - Merchant brand name
  • image: http://acmesupertoons.png (string, returned) - Merchant brand logo
  • description: We sell only stuff you really need (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

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: ==42.345139 (string, returned) - latitude
  • lon: ==12.346371 (string, returned) - longitude

PayToken

Properties

  • val: 2dd0d00a-0b71-45b0-b651-578569f7666a (string, returned) - PayToken unique ID
  • date_issued: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of PayToken issueing. Format ISO-8061.
  • date_expiring: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of PayToken expiring. Format ISO-8061.
  • charge_available: 1 (string, returned) - Max single charge amount value, matching the corresponding authorization property.

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,
  "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"
  },
  "loopback_uri": "https://application.com/?a=1&b=2&...",
  "policy": "CHARGEABLE"
}
⬇️ 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"
  },
  "loopback_uri": "https://application.com/?a=1&b=2&...",
  "policy": "CHARGEABLE",
  "sharing": "https://dp.link/u/10/CHTQA45B7PA98",
  "status": "WAITING"
}

GET - Retrieve an already challenged 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"
  },
  "loopback_uri": "https://application.com/?a=1&b=2&...",
  "policy": "CHARGEABLE",
  "sharing": "https://dp.link/u/10/CHTQA45B7PA98",
  "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,
 }
}

DELETE - Cancel a requested Authorization

Delete can be performed only on on WAITING authorizations. Otherwise an HTTP 404 status is returned.

Example

⬆️ Request
curl --request DELETE
--url https://api.drop-pay.io/shop/v1/pos/authorization/CHTQA45B7PA98
--header 'Authorization: Bearer or872y08472fhcbqc8714pquiwcnbwtwfwc'
⬇️ 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.

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.