Skip to content

DropPay API - Shop v.1 - POS - Overview

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

In your site, e-commerce, mobile application, 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.

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

Three type of POS devices exist:

  1. Application - merchant applications consuming DropPay POS API on behalf of a merchant; these devices operates directly over DropPay POS API (Payment Scheme available: DropPay, SEPA SCT);
  2. Static - a single persistent customer engagement code you can create and manage. Once it's created it can be printed as a QR code or shared as a deeplink. Whenever a DropPay user import it in his DropPay mobile application a payment flow is execute on merchant behalf (Payment Scheme: DropPay);
  3. Sepa SCT - this device lets a merchant define a regular expression that traps a Sepa Credit Transfer incoming in his Brand's payable Account, considering it as a payment and taking advantage from all the other Shop API features and tools (Payment Scheme: SEPA SCT);

For consuming POS API you need:

  • a POS Id
  • a User Access Token

The POS Id

The same Application can act as a virtual POS in any Stores of yours. Just get a POS id creating a POS with a device of type Application, already connected to the same DropPay Account of your Brand.

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.

This task can be accomplished from within the Developer Secure Area of DropPay website or through POS API, managing the pos resource.

You will obtain a value like this:

  • POS Id: POSV265V3PQ9E

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.

Then you have to:

  • ☑️ Ask user to authorize your payment proposal, by showing a special QR code or a deeplink and get a PayToken in return;

  • ☑️ Charge user once you're ready to deliver your service or good using the PayToken until it is active;

and later you can

  • ☑️ Refund user up to previously authorized amount of every single charge if something went wrong at delivering time of your service.

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 authorization you ask user to approve one among the following agreements:

  • to be charged once ;
  • 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.

Forthcoming features

Currently Authorization don't implement the following semantics:

  • Recurring multiple charges;
  • Deferred bookable balance;

See Authorization API Reference for details.

Asking user to pay (the payment engagement)

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

  1. as a link itself
  2. in a button
  3. in a QR code

User will authorize the payment by confirming it safely and securely always through his DropPay mobile app.

What's a DropPay PayToken ?

You're receiving a pay_token at the very end of every authorization flow.

A Pay Token represents the real permission granted by user and it's the mandatory property to be passed in when charging user's DropPay account.

Without a valid pay_token charging process 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.

Pay Token value is refreshing

Every time you read the authorization, until it is valid, the Pay Token is reset to let you charge user's account for a short period of time (180 secs). Conversely, you MUST read the Authorization to obtain a refreshed Pay Token useful for your further actions.

See Authorization API Reference for details also about how to correctly retrieve the pay_token.

Charge users' DropPay account

Charging is performed creating a Charge object by passing in the pay_token acquired at the end of authorization procedure.

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

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

See Charge API Reference for details.

Refund bad charges

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.

See Refund API Reference for details.