Skip to content

POS Checkout v.1 - Control API

Remember: it's not your server that initiates the Authorization procedure against DropPay, but rather it's inside the user's browser that operations start, when user clicks or taps the Pay with DropPay button.

Surely you have already opened a new purchasing order and put its reference inside the Checkout form and in your database, but your server is going to be aware of user's payment only once the authorization has been created and run.

By the way of webhooks and/or loopback_url you'll see a returning user and an Authorization ID.

That's the time to

  1. cross check your order data with Authorization details and status calling a check;
  2. retrieving the pay_token to be use in the following charge
  3. charge user's account

REST Entities

Every REST entity is described listing her properties with the following formatting conventions:

  • this is a property name
  • this is an example of property value
  • (type, policy, direction) is the specification of a property
    • type can be "string", "number", "object" or a proper object class name
    • policy can be "optional" or "required"
    • direction can be "posted" or "received" depending on whether you set it in the request or you got it from the response
  • after the dash "-" there's the property description

name: example_value (type, policy, direction) - Property description

Authorization

Properties

  • id: CHTQA45B7PA98 (string, returned) - Unique ID of the resource
  • scheme: DROPPAY (string, posted/returned, optional) - Payment scheme identifier. One of [DROPPAY,SEPASCT], default DROPPAY
  • scheme_data (object, posted/returned, optional) - Object entity according to selected Payment Scheme
  • date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - Creation date/time of the resource. Format ISO-8061
  • date_last_update: 2016-07-16T19:20:30+01:00 (string, returned) - Last update date/time. Format ISO-8061
  • status: GRANTED (string, returned) - Status label, one of [WAITING, GRANTED, EXPIRED, REVOKED, REFUSED, CANCELLED]
  • description: Your filled cart (string, posted) - Good or service description, max 512 chars
  • charge_amount: 50.00 (number, posted) - Amount of the single charge will be performed (DropPay supports only Euro currency)
  • charge_date_start: 2016-07-16T19:20:30+01:00 (string, posted) - Date/time after which charge must be accepted. Defaults to now().
  • charge_date_end: 2016-07-16T19:20:30+01:00 (string, posted/returned) - Date/time of authorization's expiration. Format ISO-8061.
  • charge_date_last: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of last executed charge. Format ISO-8061.
  • charge_max_count: 1 (number, posted) - Maximum amount of charge operation allowed by this Authorization. Must be > 0
  • charge_success_count: 1 (number, returned) - Amount of authorized charges successfully completed
  • charge_description: (string, posted) - Used if charge reason narrative is different from authorization one (i.e. "Subscription" vs. "Monthly fee")
  • pos_id: POS12562I3HG (string, posted/returned) - Merchant DropPay Shop unique identifier
  • merchant_custom_id: 13412ga723f94t02ncbcv9sf9h (string, posted) - Custom identifier set by merchant. .
  • merchant_custom_label: cart-13412ga723f94t02ncbcv9sf9h (string, posted) - Custom identifier set by merchant. .
  • merchant_business_name: ACME Ltd. (string, returned) - ragione sociale del merchant titolare del brand
  • webhooks: (Webhooks, posted) - URL DropPay will post the authorization object to after user's confirmation. Accept HTTP,HTTPS and optionally basic authentication
  • loopback_uri: https://merchant.com/?a=1&b=2&... (string, posted) - Urlencoded URI used by DropPay mobile app to drive user back to calling application. It can be a HTTP schema or a custom schema like yourapp://.... Will be appended with authorization id.
  • brand: (Brand, returned) - Brand structure containing merchant brand data
  • store: (Store, returned) - Store structure containing merchant store data
  • pay_token: (PayToken, returned) - Paytoken object
  • policy: CHARGED (string, posted) - Switch to control authorization policy to be applied to authorization. One of [CHARGEABLE,BOOKABLE,CHARGED,BOOKED].
  • sharing: https://dp.link/u/10/CHTQA45B7PA98 (string, returned) - Sharing link to be shown up to make user acquire the authorization with DropPay mobile app

Charge

Properties

  • id: CHAQA34B31FJ9 (string, returned) - Charge resource unique ID
  • authorization_id: CHTFM45B7PA98 (string, posted) - Authorization ID passed is as property when creating the charge.
  • authorization_scheme: DROPPAY (string, returned_, optional) - Payment scheme identifier. One of [DROPPAY,SEPASCT], default DROPPAY
  • pay_token_val: ec4e9e23-84b3-42b4-ba73-1bf9f39de66a (string, posted) - Paytoken unique ID referred to authorization authorization_id
  • date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - Charge creation date/time. Format ISO-8061.
  • date_done: 2016-07-16T19:20:30+01:00 (string, returned) - Charge execution date/time. Format ISO-8061.
  • date_last_update: 2016-07-16T19:20:30+01:00 (string, returned) - Charge last update date/time. Format ISO-8061.
  • pos_id: POS12562I3HG (string, posted/returned) - Merchant DropPay Shop unique identifier
  • merchant_custom_id: 13412ga723f94t02ncbcv9sf9h (string, posted) - Unique optional custom identifier for merchant tracking convenience.
  • merchant_custom_label: Double package (string, posted) - Not unique optional custom label for merchant tracking convenience.
  • merchant_business_name: ACME Ltd. (string, returned) - business name of brand owner
  • status: NEW (string, returned) - Status label, one of [DONE,FAILED,ACCOUNTED]
  • refund: (Refund, returned) - refund entity object, present only if referred charge has been refunded by merchant
  • description: Monthly Fee (string, posted) - Charge reason or.. whatever. Max 512 chars.
  • amount: 25.00 (number, posted) - Amount of charge (DropPay supports only Euro currency)
  • brand: (Brand, returned) - Brand structure containing merchant brand data
  • store: (Store, returned) - Store structure containing merchant store data

Refund

Properties

  • id: CHRV85NM121PY (string, returned) - Refund resource unique ID
  • charge_id: CHAQA34B31FJ9 (string, posted) - Charge ID passed is as property when creating the refund.
  • reason wrong order #2316 (string, posted) - Refund reason or.. whatever. Max 512 chars.
  • date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - Refund creation date/time. Format ISO-8061
  • date_last_update: 2016-07-16T19:20:30+01:00 (string, returned) - Refund last update date/time. Format ISO-8061
  • status: DONE (string, returned) - Status label, one of [DONE,FAILED, ACCOUNTED]
  • amount: 25.00 (number, posted) - Amount of refund. Must be less or equal to the amount of referred charge (DropPay supports only Euro currency)

Brand

Properties

  • id: 12qw34er5476phgkdncsd (string, returned) - ID univoco del Brand
  • name: Acme Super Toons (string, returned) - Merchant brand name
  • image: http://acmesupertoons.png (string, returned) - Merchant brand logo
  • description: We sell only stuff you really need (string, returned) - Merchant brand description or payoff
  • business_categories: (array of strings, returned) - Business Categories that characterized products and services offered by the merchant brand

Store

Properties

  • id: 12qw34er5476phgkdncsd (string, returned) - ID univoco dello Store
  • name: Rome (string, returned, optional) - Short name of the Store
  • place: REAL (string, returned) - Define is the Store is place to step in or a virtual place to be visited/read/viewed. One of [REAL, VIRTUAL ]
  • address: Piazza Navona, 25 (string, returned) - Street Address if place:REAL or any other string with the same meaning if place:VIRTUAL (webadress, magazines, etc.)
  • georef: (Store, returned, optional) - If place:REAL also georef is present.

GeoReference

Properties

  • lat: ==42.345139 (string, returned) - latitude
  • lon: ==12.346371 (string, returned) - longitude

PayToken

Properties

  • val: 2dd0d00a-0b71-45b0-b651-578569f7666a (string, returned) - PayToken unique ID
  • date_issued: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of PayToken issueing. Format ISO-8061.
  • date_expiring: 2016-07-16T19:20:30+01:00 (string, returned) - Date/Time of PayToken expiring. Format ISO-8061.
  • charge_available: 1 (string, returned) - Max single charge amount value, matching the corresponding authorization property.

Webhooks

Webhooks

  • all: URL the app's developer wants to be notified of user's confirmation of the Authorization

Add a webhook property as show below.

    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },

Port 443 allowed only (HTTPS)

Please remember that only secure HTTPS on well-known port 443 webhooks are allowed DropPay doesn't validate webhooks URL, but you won't receive any notification event.

REST Endpoints

POS Chekout Control API publishes two methods :

  • Check an Authorization
  • Charge an Authorization

Security

Requests must be authenticated with a special HTTP header

X-DropPay-Checkout-PrivateKey
whose value must be set to Checkout Private Key string returned by POS Checkout configuration previously accomplished in the Developer Secure Area of DropPay website.

X-DropPay-Checkout-PrivateKey: 83dbc70fad5243668be0d3d7c4900c76

GET - CHECK: Read the status of Authorization and obtain a fresh Pay Token

Example

⬆ Request
curl --request GET
--url https://checkout.drop-pay.com/v1/authorization/CHTQA45B7PA98/check
--header 'X-DropPay-Checkout-PrivateKey: 83dbc70fad5243668be0d3d7c4900c76'
⬇ Response 200
{
  "id": "CHTQA45B7PA98",
  "description": "Your filled cart",
  "charge_amount": 50.00,
  "charge_date_start": "2016-07-16T19:20:30+01:00",
  "charge_max_count": 1,
  "pos_id": "POSV265V3PQ9E",
  "merchant_custom_id": "cart-13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "XMas2016-campaign",
  "webhooks": {
      "ALL": "https://credenA:credenB@app.server.com/listener"
  },
  "loopback_uri": "https://application.com/?a=1&b=2&...",
  "policy": "CHARGEABLE",
  "sharing": "https://dp.link/u/10/CHTQA45B7PA98",
  "status": "GRANTED",
  "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_max_count": 1,
 }
}

POST - CHARGE: Debit user's DropPay Account with the previously obtained fresh Pay Token

Example

⬆ Request
curl --request POST
--url https://checkout.drop-pay.com/v1/authorization/CHTQA45B7PA98/charge
--header 'X-DropPay-Checkout-PrivateKey: 83dbc70fad5243668be0d3d7c4900c76'
Body
{
  "description": "Your filled cart",
  "amount": 50.00,
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
}
⬇ Response 200
{
  "id": "CHAQA34B31FJ9",
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
  "authorization_id": "CHTQA45B7PA98",
  "description": "Your filled cart",
  "amount": 50.00,
  "date_creation": "2016-07-16T19:20:30+01:00",
  "payer_name": "Donald Duck",
  "status":"DONE"
}

Webhooks & Events

Where, in the HTML FORM of Init page code, you put

<form action="/any-loopback-uri" method="POST">
  <script src="https://checkout.drop-pay.com/droppay-checkout.js" class="droppay-button"
    ...
    data-webhook="https://credenA:credenB@merchant.server.com/listener"
    ...
 </script>
</form>
you have defined a webhook for catching events notified by DropPay when working on your POS Authorization.

You'll receive events like the following one:

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "shop.pos.authorization.status_update",
    "edata": { An Authorization entity }
}

Fault tolerance

Subscribing to webhooks is optional and may be redundant with the loopback_uri, but something can go wrong when the user browser is the primary actor in the flow, so having a second chance to control what happened is definitively not a bad idea.

Errors handling

DropPay POS API is built around REST paradigm so HTTP Status code are consistently informing about what happened running your request.

Below specific API context errors are listed.

HTTP Error Statuses with ErrorInfo payload

  • Status 401 Unauthorized
  • Status 404 Not Found
  • Status 400 Bad Request
  • Status 500 Internal server error

See DropPay Common Errors for details about global common errors.