Skip to content
Magicline Device API
/
API reference
/
Vending
/
Top up customer's consumption credit

Device API

Download OpenAPI description
deviceapi.json
deviceapi.yaml
Languages
Servers
Demo tenant

https://open-api-demo.devices.magicline.com/

Mock server

https://redocly.sportalliance.com/_mock/apis/magicline/deviceapi/deviceapi/

Access

Here are all the endpoints that are necessary for GenericCardReader to be successfully used. This endpoints should be used for device with model GENERIC_CARD_READER. The model can be found in response from getDevices which was already described in authentication process.

Operations

Vending

Here are all the endpoints that are necessary for GenericVending to be successfully used. This endpoints should be used for device with model GENERIC_VENDING_READER. The model can be found in response from getDevices which was already described in authentication process.

Operations

Checks if customer is authorized to use vending device

Request

You can find more information about identification here.

Security
ApiKeyAuth
Headers
Accept-Languagestring

More information about the header can be found here.

Example: de
Bodyapplication/jsonrequired
identificationanyrequired
identification.​typestringrequired
Example: "NUMBER"
Discriminator
identification.​valuestringrequired

Card number

Example: "1233588160"
identification.​formatstring

In which format the card number value was provided. All of the following examples represent the same card number

  • DECIMAL - Card number is interpreted as string of decimal numbers.
    • Example : "1173673668653440"
  • HEX_MSB - Card number is interpreted as hex string using big-endian (from most significant to least significant byte) order.
    • Example : "042b73321a3180"
  • HEX_LSB - Card number is interpreted as hex string using little-endian (from least significant to most significant byte) order.
    • Example : "80311a32732b04"
Default "DECIMAL"
Enum"DECIMAL""HEX_MSB""HEX_LSB"
transactionIdstringrequired

Unique ID of the transaction (you have to generate it)

Example: "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
curl -i -X POST \
  https://open-api-demo.devices.magicline.com/open-api/device/vending/identification \
  -H 'Accept-Language: de' \
  -H 'Authorization: Bearer <YOUR_oauth2_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identification": {
      "type": "NUMBER",
      "value": "1233588160",
      "format": "DECIMAL"
    },
    "transactionId": "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
  }'

Responses

OK - identification has been successfully executed you can continue with sale endpoint

Bodyapplication/json
textstring

If customer is not authorized then it contains message with reason

Example: ""
authorizedboolean

If customer is authorized then is allowed to use the device

Example: true
consumptionCreditnumber

Customers consumption credit

Example: 6.4
transactionIdstring

Unique ID of the transaction

Example: "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
Response
application/json
{
  "text": "",
  "authorized": true,
  "consumptionCredit": 6.4,
  "transactionId": "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
}

Product sale (dry-run possible)

Request

This should be conducted post-identification with shouldExecuteAction = false in order to execute a dry-run, ensuring that customers can obtain the product, for example has enough credit, etc. If this first request was successful, the product can be dispensed. After the product was sucessfully dispensed, this endpoint needs to be called again with shouldExecuteAction = true, which will subsequently lead to the customer being charged. You can find more information about sale here

Security
ApiKeyAuth
Headers
Accept-Languagestring

More information about the header can be found here.

Example: de
Bodyapplication/jsonrequired
identificationanyrequired
identification.​typestringrequired
Example: "NUMBER"
Discriminator
identification.​valuestringrequired

Card number

Example: "1233588160"
identification.​formatstring

In which format the card number value was provided. All of the following examples represent the same card number

  • DECIMAL - Card number is interpreted as string of decimal numbers.
    • Example : "1173673668653440"
  • HEX_MSB - Card number is interpreted as hex string using big-endian (from most significant to least significant byte) order.
    • Example : "042b73321a3180"
  • HEX_LSB - Card number is interpreted as hex string using little-endian (from least significant to most significant byte) order.
    • Example : "80311a32732b04"
Default "DECIMAL"
Enum"DECIMAL""HEX_MSB""HEX_LSB"
transactionIdstringrequired

Unique ID of the transaction (you have to generate it)

Example: "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
productIdstringrequired

Shelf where the product is located

Example: "1"
pricenumberrequired

Price of the product according to vending machine. If the price is different than in Magicline then the request will be rejected

Example: 1.29
shouldExecuteActionboolean

In a dry run, when the value is set to false, you will receive a validation result without customer being charged. Learn more about it here.

Default true
Example: true
curl -i -X POST \
  https://open-api-demo.devices.magicline.com/open-api/device/vending/sale \
  -H 'Accept-Language: de' \
  -H 'Authorization: Bearer <YOUR_oauth2_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identification": {
      "type": "NUMBER",
      "value": "1233588160",
      "format": "DECIMAL"
    },
    "transactionId": "4671fde7-bb07-4fe5-aa0e-947d9ccb842f",
    "productId": "1",
    "price": 1.29,
    "shouldExecuteAction": true
  }'

Responses

OK - Sale check done

Bodyapplication/json
textstring

If customer is not authorized then it contains message with reason

Example: ""
authorizedboolean

If customer is authorized then is allowed to buy/use product

Example: true
consumptionCreditnumber

Customers consumption credit

Example: 6.4
transactionIdstring

Unique ID of the transaction (you have to generate it)

Example: "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
pricenumber

Price of the product

Example: 1.29
Response
application/json
{
  "text": "",
  "authorized": true,
  "consumptionCredit": 6.4,
  "transactionId": "4671fde7-bb07-4fe5-aa0e-947d9ccb842f",
  "price": 1.29
}

Top up customer's consumption credit

Request

This should be used to top up customer's consumption credit.

Security
ApiKeyAuth
Headers
Accept-Languagestring

More information about the header can be found here.

Example: de
Bodyapplication/jsonrequired
identificationanyrequired
identification.​typestringrequired
Example: "NUMBER"
Discriminator
identification.​valuestringrequired

Card number

Example: "1233588160"
identification.​formatstring

In which format the card number value was provided. All of the following examples represent the same card number

  • DECIMAL - Card number is interpreted as string of decimal numbers.
    • Example : "1173673668653440"
  • HEX_MSB - Card number is interpreted as hex string using big-endian (from most significant to least significant byte) order.
    • Example : "042b73321a3180"
  • HEX_LSB - Card number is interpreted as hex string using little-endian (from least significant to most significant byte) order.
    • Example : "80311a32732b04"
Default "DECIMAL"
Enum"DECIMAL""HEX_MSB""HEX_LSB"
transactionIdstringrequired

Unique ID of the transaction (you have to generate it)

Example: "4671fde7-bb07-4fe5-aa0e-947d9ccb842f"
amountnumberrequired

Amount customer wats to top up his consumption credit

Example: 5
curl -i -X POST \
  https://open-api-demo.devices.magicline.com/open-api/device/vending/revalue \
  -H 'Accept-Language: de' \
  -H 'Authorization: Bearer <YOUR_oauth2_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identification": {
      "type": "NUMBER",
      "value": "1233588160",
      "format": "DECIMAL"
    },
    "transactionId": "4671fde7-bb07-4fe5-aa0e-947d9ccb842f",
    "amount": 5.25
  }'

Responses

OK - The customer's consumption credit has been topped up.

Response
No content