MDB payment master daemon
If you want an easier interface to use payment methods on MDB for your solution (running on Barionet or Raspberry PI with Raspbian), we provide a payment daemon, that you can simply connect through TCP interface and start exchanging messages. The payment daemon automatically handles cashless device, coin acceptor and bill acceptor.
The Payment Master Daemon is designed to allow users to integrate it in their vending machine software. It requires TCP raw connection to interact with, which is not recommended if you are inexperienced with this sort of communication or still taking your first steps.
Installation
- Grab an archive for your device, Barionet or Raspberry/Unigate
- Unpack it on device and install
Barionet
sh install.sh
Raspberry
sudo sh install.sh
On the Unigate there is NO need to run the install.sh
Launch Payment Master Daemon
Configuration parameters can be inserted by editing startup.sh file.
sudo sh startup.sh
OR Setup autorun on boot (only raspberry)
sudo sh setup-autorun.sh
Payment master daemon is now running (or programmed to run on boot). Please refer to API Section and Testing with netcat to learn how you can interact with it using the raw socket.
Installing NodeRED custom node on Raspberry
- Make sure you have NodeRED and npm installed on your Raspberry, as well as some necessary dependencies
sudo apt-get install npm
sudo npm install -g node-red
sudo npm install -g node-red-node-pi-gpio rpi-gpio
- Install the nodered extension
cd $PAYMENT_MASTER_DAEMON_DIRECTORY # replace this with the path to the directory where the zip file of # the payment master Daemon was extracted
sudo npm install -g ./node-red-contrib-paymentdaemon/
- Start nodered
node-red start
After restarting the NodeRED, head over to the web browser and insert your <device ip>:<node-red port> where you should be able to find the payment daemon node in payment category. You can check the description of the node and checkout the examples. You can load the examples by going to the menu on the top right > Import > Examples > payment-daemon.

Daemon command line arguments
Run with parameters, example:
lua paymentMasterDaemon.lua vmc-slave-address=0x60 vmc-feature-level=2
Coin acceptor and bill acceptor are not being used by default, you need to use cash=true parameter
lua paymentMasterDaemon.lua cash=true
Supported configurations
Argument | Default | Description |
---|---|---|
cash | false | Whether to use bill acceptor and coin acceptor |
always-idle | true | Whether the daemon should be running in always-idle mode |
timeout-vend | 0 | Timeout for vend approval by cashless device or coin changer/bill validator (0=infinity) |
timeout-vend-result | 0 | Timeout for receiving vend result from host, after this time vend is considered failed (0=infinity) |
mdb-cashless-long-poll | false | Allow long response times to POLLs for cashless device (needed for some newer NAYAX readers) |
vmc-slave-address | 0x10 | Cashless device address on MDB (can be 0x60 or 0x10) |
vmc-feature-level | 3 | Feature level of the cashless daemon (can be 2 or 3) |
vmc-display-columns | 0 | Not implemented |
vmc-display-rows | 0 | Not implemented |
vmc-max-price | 0xFFFF | ADVANCED Set the maximum price for vend in base units |
vmc-min-price | 0x0000 | ADVANCED Set the minimum price for vend in base units |
tcp-allow-remote-hosts | false | To allow tcp connections outside 127.0.0.1 set this to true |
tcp-port | 31421 | TCP server port |
tcp-client-timeout | 0 | TCP communication timeout (after this many seconds of no activity - disconnect from client) (0=infinity) |
device-port | /dev/ttyAMA0 | A port handle to communicate with mdb-usb or PI hat, it defaults to AUTOFIND |
reconnect-delay | 30 | How much time to wait between reconnect tries to MDB-USB or pi hat |
verbosity | 5 | Sets the verbosity level 0 to 5: 0 - Fatal | 1 - Error | 2 - Warn | 3 - Info | 4 - Debug | 5 - Trace |
device-watchdog | false | Runs a watchdog periodically checking the connection for errors (by sending V\n every 5 seconds). If it detects that a pi hat has stopped responding it resets it reconnects. |
API
Example vend requests
Always-idle success vend
Host | Direction | Daemon |
---|---|---|
VEND,1.00\n | -> | |
Waiting for payment... | ||
<- | VEND,SUCCESS\n | |
RESULT,1\n | -> | |
<- | RESULT,SUCCESS,1\n |
Non-always-idle success vend
Host | Direction | Daemon |
---|---|---|
<- | START,10\n | |
Waiting for product selection... | ||
VEND,1.00\n | -> | |
Waiting for payment... | ||
<- | VEND,SUCCESS\n | |
RESULT,1\n | -> | |
<- | RESULT,SUCCESS,1\n |
Pay using coin acceptor or bill acceptor
Host | Direction | Daemon |
---|---|---|
VEND,1.00\n | -> | |
Waiting for payment... | ||
<- | CREDIT,0.2\n | |
<- | CREDIT,0.7\n | |
<- | CREDIT,0.9\n | |
<- | CREDIT,1.0\n | |
<- | VEND,SUCCESS\n | |
RESULT,1\n | -> | |
<- | RESULT,SUCCESS,1\n |
Vend denied
Host | Direction | Daemon |
---|---|---|
VEND,1.00\n | -> | |
Waiting for payment... | ||
<- | VEND,FAILED,VEND_DENIED\n |
Commands to daemon (HOST -> DAEMON)
Each command MUST end with a newline character ( or \n)
VEND
Syntax
VEND,{amount},{(optional)productId:[must be prefixed with *]},{(optional)startTimeout:seconds},{(optional)vendApproveTimeout:seconds},{(optional)vendResultTimeout:seconds}
Example
VEND,1.00 - Will initiate a vend with value of 1.00
VEND,1.00,*8 - Will initiate a vend with value of 1.00 for the product with ID 8
VEND,1.00,*10,30,20,20 - Will initiate a vend with value of 1.00 for the product with ID 10, with vend start timeout of 30 seconds, vend approval timeout of 20 seconds and vend result timeout (coming from master) of 20 seconds
If timeout is not specified a default value is used, the default value can be set in the arguments when starting the daemon.
Description
Initiates a vend request
Responses
Message | Description |
---|---|
VEND,FAILED,INVALID_STATE | Failed to start the session because payment devices are not in the INIT (or IDLE - with always-idle readers) state |
VEND,FAILED,MISSING_ARGUMENT | {amount} argument is probably missing |
VEND,FAILED,INVALID_ARGUMENT,{number} | Argument number {number} is invalid and cannot be parsed |
VEND,FAILED,TIMEOUT,START | Start timeout timed out |
VEND,FAILED,TIMEOUT,VEND | Vend approval timeout timed out |
VEND,FAILED,READER_RESET | Failed due to reader being reset |
VEND,FAILED,VEND_DENIED | Vend was denied |
VEND,FAILED,ESCROW_LEVER | Vend was aborted because escrow lever on coin changer was triggered |
VEND,SUCCESS,CASHLESS | Vend successful with cashless device, you MUST send either RESULT,0 or RESULT,1 after this, see RESULT command |
VEND,SUCCESS,CASH | Vend successful with cash, you MUST send either RESULT,0 or RESULT,1 after this, see RESULT command |
STOP
Syntax
STOP
Example
STOP - Stops the active session or vend request
Description
Aborts the active vend request or session
Responses
Message | Description |
---|---|
STOP,SUCCESS,POST_VEND | Session stopped during POST_VEND state due to host sending STOP command |
STOP,SUCCESS,VEND | Session stopped during VEND state due to host sending STOP command |
STOP,SUCCESS,STARTING | Session stopped during STARTING state due to host sending STOP command |
STOP,SUCCESS,CREDIT | Session stopped during CREDIT state due to host sending STOP command |
STOP,FAILED,INVALID_STATE | No ongoing vend request and no active session |
RESULT
Syntax
RESULT,{0/1}
Example
RESULT,0 - Reports negative vend result - product failed to dispense (this either refunds the used card via cashless device, or returns the money via coin acceptor) and ends the session
RESULT,1 - Reports positive vend result - product dispensed successfully, this ends the session
Description
Reports the result of the dispense/vend
Responses
Message | Description |
---|---|
RESULT,FAILED,INVALID_ARGUMENT,1 | Invalid argument 1 specified (not 0 or 1) |
RESULT,FAILED,INVALID_STATE | Failed to make vend success/failed because reader is not in POST_VEND state |
RESULT,SUCCESS,{0/1} | Successfully reported vend result |
POLL
Syntax
POLL
Example
POLL
Description
Polls the daemon for the current state of connected devices
When tcp-client-timeout is specified in the startup parameters (not by default). It is advised to use this command to keep the connection alive!
Responses
Message | Description |
---|---|
STATE,{cashlessState},{coinChangerState},{billValidatorState} | The state of the devices |
Cashless device states
State | Description |
---|---|
DISCONNECTED | MDB USB or MDB pi hat is not connected |
CONNECTED | Connected to MDB USB or MDB pi hat |
RESET | Cashless device inactive |
INIT | Cashless device setup |
STARTING | Enabling the reader |
IDLE | Reader enabled and IDLE |
CREDIT | Card was inserted and there is credit available |
VEND_REQ | Vend request was intiated |
POST_VEND | Vend request processed |
Coin changer states
State | Description |
---|---|
OFFLINE | Coin acceptor disconnected |
RESET | Performing reset procedure |
RESET_POLL | Coin acceptor is being polled for Just Reset response |
SETUP | Setup command sent to coin acceptor |
COIN_TYPE | Enabling coin acceptor |
ENABLED_IDLE | Coin acceptor enabled |
CREDIT | Coin or multiple coins were deposited to the coin acceptor |
VEND_REQ | Vend request was intiated |
POST_VEND | Vend request processed |
Bill acceptor states
State | Description |
---|---|
OFFLINE | Bill acceptor disconnected |
RESET | Performing reset procedure |
RESET_POLL | Bill acceptor is being polled for Just Reset response |
SETUP | Setup command sent to bill acceptor |
BILL_TYPE | Enabling bill acceptor |
ENABLED | Bill acceptor enabled |
CREDIT | Bill was deposited to the bill validator |
VEND_REQ | Vend request was intiated |
POST_VEND | Vend request processed |
VERSION
Syntax
VERSION
Example
VERSION
Description
Requests the daemon version
Responses
Message | Description |
---|---|
VERSION,{version} | Payment daemon is running {version} |
Currently documented version is 0.5
DISPENSE
Syntax
DISPENSE,{value}
Examples
DISPENSE,1.00 - dispenses value of 1.00 through the coin acceptor
DISPENSE,2.50 - dispenses value of 2.50 through the coin acceptor
Description
Dispenses the specific amount in coins from the coin acceptor.
This is generally not needed, since payment daemon handles paying out change automatically. But could be used if you want to manually dispense the coins.
Responses
Message | Description |
---|---|
DISPENSE,1 | Dispense successful |
DISPENSE,0 | Dispense failed |
TUBE_STATUS
Syntax
TUBE_STATUS
Examples
TUBE_STATUS - sends a request to return the tube status of connected coin acceptor
Description
Sends a request to return the tube status of connected coin acceptor
Responses
Message | Description |
---|---|
TUBE_STATUS,FAILED,COIN_CHANGER_NOT_SUPPORTED | Coin changer is disabled by config option |
TUBE_STATUS,FAILED,COIN_CHANGER_DISCONNECTED | Coin changer not connected or not initialized |
TUBE_STATUS,FAILED,COIN_CHANGER_NOT_READY | No tube status received from coin changer yet |
TUBE_STATUS,SUCCESS,{coin 0 count},{coin 0 full [0/1]},{coin 1 count},{coin 1 full [0/1]},... | Request success |
Commands from daemon (DAEMON -> HOST)
START
Syntax
START,{credit}
Example
START,1.00 - A card was presented with the amount of 1.00 authorized
START,2.50 - A card was presented with the amount of 2.50 authorized
Description
Sent when payment medium with credit is presented to the cashless device with specific amount of funds that can be used to initialize a vend request.
Only if not using always-idle. This means authorize-first.
END
Syntax
END
Example
END
Description
Sent when payment medium is ejected from the cashless device in CREDIT state. Or when escrow button is pressed on coin changer, in that case the whole credit is dispensed.
Only if not using always-idle. This means authorize-first.
CREDIT
Syntax
CREDIT,{value}
Example
CREDIT,0.8 - Indicates that 0.80 was already given to the machine by the means of bill acceptor or coin acceptor
Description
Indicates the amount of credit already given to the machine via bill acceptor or coin acceptor, you can use this to display the amount left to be paid on screen!
Only when bill acceptor or coin acceptor is used for the payment.
ERROR
Syntax
ERROR,{error type}
Examples
ERROR,SERIAL_ CONN_ LOST - Error, serial connection to pi hat or mdb-usb has been lost
Description
Informs the host about any error that happened.
Responses
Message | Description |
---|---|
ERROR,SERIAL___CONN___LOST | Serial connection to the pi hat or mdb-usb has been lost |
ERROR,CASHLESS_OFFLINE | MDB Cashless device went offline |
ERROR,COINCHANGER_OFFLINE | MDB Coin changer wen offline |
ERROR,BILLVALIDATOR_OFFLINE | MDB Bill acceptor/validator went offline |
Testing with Netcat
Payment master daemon can be tested using netcat tool in Linux (Raspbian and Barionet's OS) systems.
netcat <lopback ip> 31421
Below there is an example on how to write commands to the Payment Master Daemon using netcat. The next examples will show a vending session on Always Idle and Auth First, but any command defined in the previous section can be issued.
To perform a vending session you can use a cashless reader or a MDB USB. The next examples we used a MDB UDB
Always Idle
POLL
STATE,IDLE #THIS IS A RESPONSE
VEND,1 #REQUEST A VEND OF 1 (CURRENCY) CREDIT
VEND,SUCCESS #THIS IS A RESPONSE - SAYING THAT THE VEND WAS SUCCESS
RESULT,1 #FINISH THE VENDING
RESULT,SUCCESS,1 #THIS IS A RESPONSE - SAYING THAT THE VEND WAS SUCCESSFUL
C,1 #ENABLE THE READER
c,STATUS,INACTIVE
r,ACK
c,STATUS,DISABLED
r,ACK
r,ACK
c,STATUS,ENABLED #THIS IS A RESPONSE - SAYING THAT THE READER IS READY
c,STATUS,VEND,1.00,0 #THIS IS A RESPONSE - SAYING THAT A REQUEST WAS SENT
C,VEND,1 #APPROVE 1 (CURRENCY) CREDIT
r,ACK
c,VEND,SUCCESS
c,STATUS,IDLE
c,STATUS,ENABLED #THIS IS A RESPONSE - SAYING THAT THE READER IS READY AGAIN
r,ACK
Authorization first
START,5.00 #THIS IS A RESPONSE - SAYING THAT THE MACHINE HAS 5 (CURRENCY) CREDIT
VEND,2 #REQUEST A VEND OF 2 (CURRENCY) CREDIT
VEND,SUCCESS #THIS IS A RESPONSE - SAYING THAT THE VEND WAS SUCCESS
RESULT,1 #FINISH THE VENDING
RESULT,SUCCESS,1 #THIS IS A RESPONSE - SAYING THAT THE VEND WAS SUCCESSFUL
C,1 #ENABLE THE READER
c,STATUS,INACTIVE
r,ACK
c,STATUS,DISABLED
r,ACK
r,ACK
c,STATUS,ENABLED #THIS IS A RESPONSE - SAYING THAT THE READER IS READY
C,START,5 #GIVE CREDIT TO THE MACHINE
c,STATUS,IDLE,5
r,ACK
c,STATUS,VEND,2.00,0 #THIS IS A RESPONSE - SAYING THAT A REQUEST WAS SENT
C,VEND,2 #APPROVE 2 (CURRENCY) CREDIT
r,ACK
c,VEND,SUCCESS
c,STATUS,IDLE
c,STATUS,ENABLED #THIS IS A RESPONSE - SAYING THAT THE READER IS READY AGAIN
r,ACK