DropPay API - Quick Start¶

Here we're getting through a simple payment example to explore every important concept and technical aspect you have to get familiar with, when building applications on top of DropPay API.

We built the following example on top of POS API, because we expect it to be the most popular and frequently used of our APIs, but out of the DropPay POS specific resources and procedures, all the rest is common in whole the DropPay API.

In order to make you focus as much as possibile on the main pillars we're considering a very simple case in simplified but very realistic conditions:

The BoxOffice Example¶

1. you're a DropPay Business Account owner
2. you want to sell event tickets
3. you're a developer
4. you're building a new e-commerce application

DropPay offers two ways to collecting payments when your application can communicate on Internet (if you're building something it can not access the Internet, DropPay won't help you).

• DropPay POS API - RESTful API
• DropPay POS Checkout - Plug&Play HTML embeddable Javascript

In this example we're going to drive you along a simple but full DropPay POS API running flow. If you're looking for a quick & easy way to collect payments from your web site, without the need to create and run an integrated DropPay Application jump directly to DropPay POS Checkout page and learn how to get paid with it.

DropPay entities you must get confident with¶

In this example we'll touch DropPay things like

• Application: the code you run;
• Brand: the brand of your business, referred to your DropPay Business Account;
• Store: the real or virtual place where your products are sold;
• POS: the virtual device you're going to use to collect payments in a specific Store;

When you act as a merchant, you run your Application as a POS virtual device to receive the amount of a payment in the DropPay Business Account you have chosen for a Brand the Store visited by your customer belongs to.

It seems complicated but it's not, because DropPay is barely trying to reflect the real world: a customer is purchasing a product in a Store of your Brand and you have deployed a POS device to let him pay with his DropPay Account. The device is actually your Application.

Step 1. Create an Application¶

Sign in at secure.drop-pay.com

Get to Developer Area and create a new Application filling the form fields

Copy Application Key and Application Secret values

Example¶

• Application Key: 70daac494c7847dba33725b075608cc0 ¹
• Application Secret: 91c9adaa829545c1934b96490ba2b9b1 ¹

Step 2. Connect your DropPay account¶

Now you have to authorize your own new application to work with one of your DropPay Business Accounts. Your Application is about to work as a virtual POS of your Brands.

You need the Connection Code.

A Connection Code represents the relation established between an Application and one of your DropPay accounts. Its value must be kept secret and in safe place along with Application Secret. A DropPay custom application will use the Connection Code to obtain an OAuth2 valid Access Token.

Open freshly created application details and add an account connection by clicking on the chain small icon on the right. A QR code will appear on screen.

Fire up your DropPay mobile application and scan the QR code.

Choose a Business Account from the available list and confirm the Connection;

Get back to DropPay Secure website and Copy the "Connection Code" DropPay has just created for you by clicking the curly brackets button.

• Connection Code: ac9185e9f29adf7238fkj9fd2881ff1a¹

The procedure to obtain a Connection Code described above is useful when your application is designed to work with your own DropPay account, we say that Application Owner and Account Owner are the same DropPay User. When this is not the case, Connections can be created using DropPay Connection API directly from you app against an other DropPay User.

This procedure is performed once, or only after a previously existent Connection has been revoked and should be restored.

Step 3. Choose the Connected Application as a POS¶

Now that you have an Application enabled to consume DropPay API on behalf of yourself using your Business Account as counterparty of all financial operations, DropPay gives you a new parameter: the POS Id.

Get in the Developer Secure Area of the DropPay website and choose a Brand and one of its Store to deploy you POS device into.

You're obtaining what elsewhere in the world is often called terminal id. We call it POS Id.

• POS Id: POSV265V3PQ9E¹

Your Application can act as POS Device for several Stores. Simply get as many POS Id as you need.

Every time you have to initiate a payment procedure to collect payment for a particular Brand and Store use the same POS Id.

At Step 5, further on this page you'll learn how to use it.

Step 4. Get an Access Token¶

Time to fire up a terminal, and start hitting DropPay API:

curl --request POST --url https://api.drop-pay.io/oa2/v1/ac/token

{
    "grant_type": "authorization_code",
    "code": "ac9185e9f29adf7238fkj9fd2881ff1a",
    "client_id": "70daac494c7847dba33725b075608cc0",
    "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
    "scope": "app"
}

We simply have to set

• code = Connection Code value
• client_id = Application Key value
• client_secret = Application Secret value

If everything is correctly processed DropPay answers with

{
    "token_type":   "bearer",
    "access_token": "a43baf630b964c049dcfba1031d2c43e",
    "expires_in":   3600,
    "refresh_token":"0b78c87d136044c79e3328caf5d66158"
}

The Access Token value is your first achievement

• Access Token: a43baf630b964c049dcfba1031d2c43e¹

Step 5. Ask user to pay¶

Now its time to get back to your business. Imagine you're a event ticket reseller. Every ticket corresponds to a booked seat. So you set up a purchase user experience that ends with the payment request.

Suggest user to Pay with DropPay and call the authenticated API:

curl --request POST
--url https://api.drop-pay.io/shop/v1/pos/authorization
--header 'Authorization: Bearer a43baf630b964c049dcfba1031d2c43e'

{
    "description": "The Musical - Booking Seat",
    "charge_amount": 50.00,
    "pos_id": "POSV265V3PQ9E",
    "webhooks": {
        "ALL": "https://yourbooking.com/listener"
    },
    "loopback_uri": "https://yourbooking.com/order/12392803/",
}

DropPay will respond with

{
  "id": "CHTQA45B7PA98",
  "description": "The Musical - Booking Seat",
  "charge_amount": 50.00,
  "charge_date_start": "2017-03-16T19:20:30+01:00",
  "charge_maxcount": 1,
  "pos_id": "POSV265V3PQ9E",
  "webhooks": {
      "ALL": "https://yourbooking.com/listener"
  },
  "loopback_uri": "https://yourbooking.com/order/12392803/",
  "sharing": "https://dp.link/10/CHTQA45B7PA98"
}

1. if you detect he's browsing your site from a smartphone, display a button

   [](https://dp.link/10/CHTQA45B7PA98)

2. otherwise simply generate a QR code

   

Waiting for the payment authorization approval¶

Once you have shown the sharing link the control is in your customer's hand, and you can not do more than wait...

User will be aware the authorization is coming from your shop, he will verify the description and the amount and finally he will endorse it with his secure PIN.

Step 6. Get the payment authorization¶

Ok, user has accepted his account to be charged with the amount of your payment proposal.

Then DropPay is either:

• redirecting user to "loopback_uri": "https://yourbooking.com/order/12392803/?dps=1&dpcht=CHTQA45B7PA98",
• POSTing Authorization data as a JSON payload to the "webhook": "https://yourbooking.com/listener"

inside the authorization entity you will able to find a new object:

"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 value is your achievement.

Step 6. And finally charge your customer¶

You got the payment authorization, so now you can submit the seat booking procedure, retrieve reservation data and prepare the ticket to be delivered.

Let's take the money then:

curl --request POST
--url https://api.drop-pay.io/shop/v1/pos/charge
--header 'Authorization: Bearer a43baf630b964c049dcfba1031d2c43e'

{
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
  "description": "The Musical - Booking Seat row 8 - seat 16",
  "amount": 50.00,
}

If DropPay is responding with a wonderful 200 HTTP Status code, all tasks are accomplished. You got the money into your DropPay Business Account.

Now explore all the DropPay POS API features!