Skip to content

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 DroPay 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 you DropPay Business Account;
  • Store: one 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 1
  • Application Secret: 91c9adaa829545c1934b96490ba2b9b1 1

Remember

Application Key is static and immutable. Application Secret can be reset manually

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're a Merchant!

Remember that you're acting as a merchant, so the Business Account you're connecting and the Business Account of your Brand must be the same.

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: ac9185e9f29adf7238fkj9fd2881ff1a1

Remember

Connection Code is static and immutable. You can only revoke the corresponding Connection through the mobile app and create a new one repeating the same procedure. Connection Code is a secret string.

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: POSV265V3PQ9E1

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:

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

1
2
3
4
5
6
7
{
    "grant_type": "authorization_code",
    "code": "ac9185e9f29adf7238fkj9fd2881ff1a",
    "client_id": "70daac494c7847dba33725b075608cc0",
    "client_secret": "91c9adaa829545c1934b96490ba2b9b1",
    "scope": "app"
}
Someone of you who's familiar with OAuth2 could have recognized the keys listed in the JSON above.

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

1
2
3
4
5
6
{
    "token_type":   "bearer",
    "access_token": "a43baf630b964c049dcfba1031d2c43e",
    "expires_in":   3600,
    "refresh_token":"0b78c87d136044c79e3328caf5d66158"
}

☑️ The Access Token value is your first achievement

  • Access Token: a43baf630b964c049dcfba1031d2c43e1

Remember

Access Token expires after expires_in seconds. You must request another Access Token using the refresh_token or a new one from scratch. See Authentication v.1 API Reference for details.

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:

1
2
3
curl --request POST
--url https://api.drop-pay.io/shop/v1/pos/authorization
--header 'Authorization: Bearer a43baf630b964c049dcfba1031d2c43e'
1
2
3
4
5
6
7
8
9
{
    "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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "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"
}
Use the sharing value to invite your customer to acquire the authorization with his DropPay Mobile app:

  1. if you detect he's browsing your site from a smartphone, display a button
    PDP
  2. otherwise simply generate a QR code
    QR

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:

1
2
3
4
5
6
"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:

1
2
3
curl --request POST
--url https://api.drop-pay.io/shop/v1/pos/charge
--header 'Authorization: Bearer a43baf630b964c049dcfba1031d2c43e'
1
2
3
4
5
{
  "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.

Summary

For your convenience here below the list of steps we got through:

  1. Create a new Application: application_key and application_secret (ONCE);
  2. Connect app to a Business Account: connection_code (ONCE);
  3. Set the Application as a POS Device for a Brand and a Store of yours (ONCE);
  4. Request an access token: access_token (PER AUTHENTICATION SESSION);
  5. Challenge for a new payment authorization: pay_token (PER PAYMENT AUTHORIZATION);
  6. Charge User's account (PER PAYMENT CHARGE).

Now explore all the DropPay POS API features!


  1. your value(s) can be obviously different