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.

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.

"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,
  }

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

`"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 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

Charge¶

Brand¶

Store¶

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. User Access Token can be obtained requesting it with and active Connection Code.

Details at Authentication v.1 API Reference

POST - Charge an account¶

Example¶

Request¶

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

{
  "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¶

{
  "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¶

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

Response¶

{
  "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.

See DropPay Common Errors for details about global common errors.