Skip to content

DropPay API - Shop v.1 - POS - Charge

Once an Authorization has been successfully challenged, your application can start charging the user account using a fresh pay_token.

Warning

Only a merchant is authorized to charge. So your application must act on behalf of the DropPay Business account owner who is the merchant party of the authorization you want to charge.

Read Connection API reference first!

DropPay Pay Token

You're receiving a pay_token at the very end of each successful authorization flow. The Pay Token is the mandatory property to be passed in when charging a DropPay user. Not using a valid pay_token will result in a failure.

Here below an example of pay_token is shown.

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:33+01:00",
    "charge_available": 1,
  }
A pay_tokenis issued at pay_token.date_issued and must be consumed before pay_token.date_expiring for a maximum of pay_token.charge_available times. pay_token.charge_available should be the difference between
authorization.charge_max_count and authorization.charge_success_count (see also Authorization REST entity below).

The pay_token lifetime is limited to about 180 seconds. Every time you GET an Authorization DropPay verifies if the lifetime has expired. If so, and the Authorization itself is still valid, the pay_token lifetime is reset and it becomes newly available for a charge command.

Charging scope

Authorization defines the scope your charging actions have to to be compliant with:

  • how many charge are authorized: authorization.charge_max_count
  • the amount of each charge: authorization.charge_amount
  • the time since charges are allowed: authorization.charge_date_start
  • the time until charges are allowed: authorization.charge_date_end
  • you can book an amount balance before charging : authorization.policy

Any attempt to POST a charge outside its scope will result in an error.

Charging reserved credit

When the authorization has been challenged with a booking policy you can charge it up to its amount value (and not more).

For example if authorization.charge_amount was 100.00 you could set

1
`"amount": 54.72`

in the charge request. Only the partial amount will be charged and the rest of it will be released in the user's available balance.

Charging CHARGED authorizations

When an Authorization has been created with the policy set to CHARGED, charge is not needed because DropPay will already have attempted to execute it at the moment user granted the Authorization using DropPay mobile app.

Any attempt to charge a challenged CHARGED authorization will result in an error.


REST Entities

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

  • this is a property name
  • this is a property value
  • (type, returned) is the type of a returned property
  • (type, posted) is the type of a requested property
  • after "-" there's a description

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

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) - Store unique id
  • 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.

REST Endpoints

DropPay POS API publishes two methods :

  • POST a new Charge entity to charge DropPay user's account
  • GET the Charge entity to read the payment status;

Security

Requests must be authenticated with User Access Token

Details at Authentication v.1 API Reference

POST - Charge an account

Example

⬆️ Request
1
2
3
curl --request POST
--url https://api.drop-pay.io/shop/v1/pos/charge
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
1
2
3
4
5
6
7
8
{
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
  "authorization_id": "CHTFM45B7PA98",
  "description": "ACME Commerce Cart Payment",
  "amount": 25.00,
  "merchant_custom_id":"13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "Double package"
}
⬇️ Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "CHAQA34B31FJ9",
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
  "authorization_id": "CHTFM45B7PA98",
  "description": "Monthly Fee",
  "amount": 25.00,
  "merchant_customid":"13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "Double package",
  "date_creation": "2016-07-16T19:20:30+01:00",
  "payer_name": "Donald Duck",
  "status":"DONE"
}

GET - Verify the charge

Example

1
2
3
curl --request GET
--url https://api.drop-pay.io/shop/v1/pos/charge/CHAQA34B31FJ9
--header 'Authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
⬇️ Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "CHAQA34B31FJ9",
  "pay_token_val": "ec4e9e23-84b3-42b4-ba73-1bf9f39de66a",
  "authorization_id": "CHTFM45B7PA98",
  "description": "Monthly Fee",
  "amount": 25.00,
  "merchant_customid":"13412ga723f94t02ncbcv9sf9h",
  "merchant_custom_label": "Double package",
  "date_creation": "2016-07-16T19:20:30+01:00",
  "payer_name": "Donald Duck",
  "status":"DONE"
}

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 410 Gone
    • Code 200 Pay token is expired

See DropPay Common Errors for details about global common errors.