Adding PushCoin Payments to vending machines

Here we describe steps for adding PushCoin Payments to school vending machines. PushCoin Payments are added to vending machines to address shortages of cafeteria staff, speed up lunch lines, increase revenues, and extend the hours of serving food. Although vending machines typically serve snacks and beverages, there are units capable of dispensing hot meals such as pizzas, soups, burritos and freshly baked cookies. Since vending machines operate without supervision of cashiers, students themselves make selections of products and authenticate using a PIN-pad. Furthermore, the machines recognize if a student is on the National School Lunch Program, enforce daily limits and protect Student Wallets with additional levels of security controlled by the parents.

Transaction flow

A typical vending machine transaction consists of the following steps:

  1. Student selects a product.
  2. Student enters the Student ID and a Security PIN set up in the PushCoin account by the parent.
  3. The vending machine makes a web request to PushCoin, which authenticates the student and checks for sufficient balance in the Wallet.
  4. If the web request returns a success code, the vending machine serves the selected product.

Request payload and the Internet endpoint

The vending machine makes the HTTPS POST request to the following endpoint: https://api.pushcoin.com/api/v1/guest/transactions/vending

The request payload is a JSON message, formatted as follows:

{
  "items": [
    {
      "sku": "<Product SKU>",
      "qty": "1"
    }
  ],
  "client_submission_id": "<Client Transaction ID; UUID>",
  "customer_pin": "<Entered Security PIN>",
  "user_ext_id": "<Entered Student ID>"
}

If successful, the backend returns HTTP Code 200 and a JSON response:

{
  "schema": "pushcoin:reply.1",
  "resource": "transactions/vending",
  "text": "Success",
  "status": 200,
  "response": {
    "submission_id": "<PushCoin Transaction ID>",
    "client_submission_id": "<Client Transaction ID>"
  }
}

If unsuccessful, the backend returns HTTP Code 400 and the text attribute of the response describes the error. The vending machine is expected to display this error to the user. Below is a Wrong PIN message, as an example.

{
  "schema": "pushcoin:reply.1",
  "resource": "transactions/vending",
  "text": "Wrong PIN",
  "status": 400
}

Request authentication

The backend authenticates requests using the HTTP Basic Authentication protocol defined in RFC 7617. In this scheme, the username and password are Base64-encoded and passed in the Authentication Header. Below is a cURL example that demonstrates making the request with the credentials passed via the –user command-line option:

curl -X POST "https://api.pushcoin.com/api/v1/guest/transactions/vending"
   --user "<School ID>:<Vending Machine ID>"
   -H "Content-Type: application/json"
   -H 'Accept: application/json'
   -d "<JSON PAYLOAD>"

Every vending machine is configured with the School ID and the Vending Machine ID which must accompany every PushCoin transaction.

Request a test account

To request a demo account and start testing your vending machine’s integration, please email PushCoin Support at ask@pushcoin.com

We will provide credentials to a sandbox account where you can safely submit test transactions.