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

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

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.

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

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

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

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¶

Brand¶

Store¶

GeoReference¶

PayToken¶

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

See DropPay Common Errors for details about global common errors.