POS Checkout v.1 - Overview¶

...because there's always an easier way...¶

If you have just an e-commerce web site, that is regular enough not to need very fine customizations of its UX, DropPay gives you Checkout, a DropPay POS Device you can add to your internet store and start collecting payments.

Whereas DropPay POS API is the fully featured foundation API that enables your real DropPay Application to collect payments from DropPay Account Owners, DropPay POS Checkout is the nearly plug&play solution that, with some limitations compared to its bigger brother, makes that all the same possible without the need to be compliant with the full DropPay Security Model.

All the same, we recommend you to read at least the Shop API Overview to learn concepts and entity names, before using checkout.

To run POS Checkout you must be ready to:

register a new POS Checkout Configuration through the Developer Secure Area of DropPay website;

create a FORM element in the payment HTML Init page code of your web based application within a DIV element, with purchase settings;

prepare your site to perform two simple HTTP request against Checkout Control API;

... wait for money coming in...

DropPay will build user interface components for you on the fly, out of the box of your page, in an overlaid modal window. Then it returns to your site with payment ready to be settled. You just have to cross check your data and charge user.

What is a POS Virtual Device in DropPay?¶

Figure out a DropPay POS as a virtual device you enable (in the DropPay Secure website) to process payments in one of the Stores of a Brand of yours.

Four type of POS virtual devices exist:

1. Checkout - a featured web payment UX kit hosted and run by DropPay (actually what we are describing hereby);
2. Static - a single persistent customer engagement code you can create and manage with DropPay Shop Tools of DropPay Secure website (this topic is out of the scope of these pages).
3. Sepa SCT - this device lets a merchant define a regular expression that traps an incoming Sepa Credit Transfer in his Brand's payable Account. This device considers it as a payment in the payment scheme: SEPA SCT.
4. Application - DropPay Applications consuming DropPay POS API on behalf of a merchant (the most of this site is dedicated to DropPay Applications);

To be able to work with all of them except the Checkout one, you must connect your application to the Full DropPay API, while Checkout is a higher level tool designed to help webmasters.

Understanding the DropPay POS Authorization¶

A POS Virtual Device is an program that requests a POS Authorization using Shop module API, namely a permission given by a payer user to a DropPay merchant that enables the latter to charge a user's DropPay payment account.

Once the merchant got the Authorization, he's able to charge or to book & charge later his customer's account within the scope defined by the Authorization itself.

A single Authorization, many business cases¶

DropPay POS Checkout is as powerful as you expect and possibly more. You can ask for a single simple payment or for a sequence of multiple payments (recurring or not) and you can ask for booking an amount of credit to be charged at the end of product or service delivery process.

From user's point of view, then, when you create a new Authorization, you ask user to approve one among the following agreements:

to be charged once ;

to be charged more than once, up to a maximum number of times (or unlimited), until an expiration date ;

to be charged more than once, up to a maximum number of times, with a defined recurring period, until an expiration date.

to have his account balance booked by a defined amount of credit that is going to be charged later, up to the booked amount

All those semantics are controlled by Authorization properties at creation time.

Authorization is represented as a JSON object and Checkout is using quite the same payload as the DropPay POS API one. See Authorization API Reference for details.

Sign in the web DropPay site at secure.drop-pay.com, then go to the developer area and follow the instruction to create a new POS Checkout Configuration.

You will obtain a ready to use HTML code snippet, a dedicated secret key valid for charging requests and a list of friendly hints. Learn how to set up your checkout page.

Asking user to pay (the payment engagement)¶

DropPay wants a Payment Authorization is explicitly acquired and set by a DropPay account owner using his own mobile app. DropPay offers you a simple way to accomplish this task by presenting a deep link like the following one:

in a modal window opened upon you own e-commerce site checkout page.

User will authorize the payment by confirming it safely and securely through his DropPay mobile app thats works as a strong authentication second factor device.

From then on, the Authorization is resulting granted and will be able to be charged or booked & charged using a special temporary credential it carries on called pay_token.

What's a DropPay PayToken ?¶

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 value 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 its lifetime has expired. If it happens, but the Authorization itself is still valid, the pay_token lifetime is reset so that it can be used for a new charge command.

Pay Token is part of Authorization payload.

Acquiring the Pay Token (being notified)¶

Once DropPay user has granted the Authorization, 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 set in loopback_uri parameter.

3. webhook is a server URL on HTTP(S)

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

At the very end of loopback_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.

See Webhooks& Events in Checkout Control API Reference for details.

Checkout Flow¶

The Checkout flow starts when user clicks/taps a button on checkout page of your e-commerce site, then it continues with user that authorize DropPay to enable your site to charge his Account (using DropPay mobile app), and it ends with your site cross checking the user confirmation and charging him.

DropPay Checkout takes care of DropPay POS payment User Experience, built upon the DropPay POS API, for you.

Once your page is correctly prepared, this is the workflow a consumer is expected to deal with:

Consumer loads your payment page in his browser

DropPay Checkout client side javascript code runs and shows first a special button "Pay with DropPay"

Once the button is clicked a DropPay controlled overlaid modal window is shown

DropPay Checkout initializes a new payment Authorization in the backstage;

DropPay Checkout shows up a QR code or a deeplink (useful when user is running a smartphone browser) detecting user's device type;

User is challenged to launch his DropPay mobile app and to approve the payment Authorization;

DropPay mobile app redirects user back to your web site page along with Authorization reference;

Your site cross checks the Authorization returned with purchasing order data and requests a charge on the same Authorization using the pay token.

User's using his mobile device to scan a page viewed on an other browser¶

This scenario is happening when your customer is browsing your checkout page with a desktop/laptop browser. A QR code is going to be shown asking to be scanned.

The picture below shows the collaboration diagram describing that case.

User's browsing your e-commerce site with the same mobile device DropPay is installed onto¶

This scenario is happening when your customer is browsing your checkout page with his mobile device browser. A button is going to be shown asking to be tapped in order to switch foreground app to DropPay.

The picture below shows the collaboration diagram describing that case.

Charge users' DropPay account¶

Charging is performed requesting a Charge by passing in the pay_token acquired from the Authorization payload by a Check request.

You can use the pay_token as many times as the corresponding authorization enables you to and until it expires.

Charge is represented as a JSON object and Checkout is using quite the same payload as the POS API one. Se the Charge REST entity article Checkout Control API Reference).

Further Details¶

A full reference of POS Checkout can be found at the following pages:

Checkout Init page code¶

Checkout Control API Reference¶