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.

Warning

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

Warning

On the Unigate there is NO need to run the install.sh

Launch Payment Master Daemon

Info

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

Success

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

Info

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

Info

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)

Info

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

Info

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

Info

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}

Info

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.

Info

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.

Info

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.

Info

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!

Info

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

Last updated on