DropPay API¶

Shop v.1 - POS¶

Overview¶

DropPay Point Of Sale (POS) API includes methods to collect payments from your customers.

In your site, e-commerce and in mobile, desktop or server application, or, actually whatever you have built, you can provide your customer a successful way to pay with his own DropPay Account, with a payment card or with other payment method is available, for your application, as DropPay Virtual POS Device.

Imagine a DropPay POS as a interface of an active resource that process all the phases of a digital payment:

initiating an Authorization procedure (Authorization)
receive the confirmation of that Authorization (granting)
enable your merchant application to Charge customer payment account (Charge)
let your merchant application refund user if needed (Refund)

Every DropPay POS is created in a Store. A Brand can have multiple Stores and a Store can have multiple POS.

A DropPay POS can be attached to one and only Virtual POS Device.

Depending upon which is the Virtual POS Device is enabled in your POS interface, your POS will possibly handle Authorizations, Charges and Refund in a different way.

For some types of Virtual Device your application can manage the POS, partially modifing its settings through the Virtual Device Managing API, for others managing API will be completely unavailable because they are constrained by DropPay platform and their settings are fixed.

DropPay POS payment APIs¶

The payment APIs the DropPay POS enabled are :

Authorization
Charge
Refund

Here below they are described without referring them to any particular Virtual POS Device.

In a real case you'll always make use of a POS attached to a specific Virtual Device that fully implements or not all the POS features and define cause and effects relationship among Authorisation, Charges and Refund.

Please read the API reference of you Virtual POS Device POS Devices overview page for further details.

Authorization¶

A single Authorization, many business cases¶

DropPay POS API is as powerful as you expect and possibly more. You can ask for a single simple payment, for a sequence of multiple payments (recurring or not) and you can book for a credit to be charged at the end of good or service delivery.

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

to be charged once possibly later;
to be charged once at authorization time ;
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, recurring by a defined period, until an expiration date;
to have his account balance booked at authorization time by a defined amount of credit that is going to be charged later up to booked value
to have his account balance bookable by a defined (or undefined) amount of credit that is going to be charged later, up to booked value

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

Every Virtual POS Device enable its own set of features

Remember, not all the features listes above can be found in every Virtual POS Device

Forthcoming features

Currently Authorization don't implement the following semantics:

Recurring multiple charges;
Deferred bookable balance;

For consuming POS API you need:

a POS ID
a User Access Token

The POS ID

This task can be accomplished from within the Developer Secure Area of DropPay website where you can find the POS ID also when a DropPay POS is created for you by the DropPay staff.

You will obtain a value like this:

POS Id: POSV265V3PQ9E

Brand Account and Connected Account must be the same

Please keep in mind it as very important constraint. Application performing requests against POS API on behalf of a merchant must have been connected to the same DropPay Account the Brand is using as payable account.

The User Access Token

Your Application can initiates payment procedure on behalf of a merchant only if it can consume DropPay POS API as it was logged in as the mercahnt himself.

So, make sure you have a valid Connection Code to retrieve a valid Access Token as well. See DropPay Security Model for details.

Charge - Charge users' DropPay account¶

Charging is performed creating a Charge object referred to the GRANTED Authorization previously obtained.

If you choose to have user implicitly charged at authorization time (suitable for a single payment and know as "charged" policy ), charging attempts will result in a failure and a 403 - FORBIDDEN HTTP response status is returned.

Refund - Refund bad charges¶

When available in the Virtual POS Device attached to the DropPay POS your app has used to perform the Authorization, occasionally you might want to refund user closing an issue previously opened by your customer support team.

This task is accomplished by creating a Refund object and referring it to an already successfully performed Charge.

You can refund user totally (that's the default behavior) or partially up to the amount value of the referred charge.

Go to Virtual POS Devices page