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

  1. Grab an archive for your device, Barionet or Raspberry/Unigate
  2. Unpack it on device and install

Barionet

Bash
Copy

Raspberry

Bash
Copy

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.

Bash
Copy

OR Setup autorun on boot (only raspberry)

Bash
Copy

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
Bash
Copy
  • Install the nodered extension
Bash
Copy
  • Start nodered
Bash
Copy

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:

Bash
Copy

Coin acceptor and bill acceptor are not being used by default, you need to use cash=true parameter

Bash
Copy

Supported configurations

ArgumentDefaultDescription
cashfalseWhether to use bill acceptor and coin acceptor
always-idletrueWhether the daemon should be running in always-idle mode
timeout-vend0Timeout for vend approval by cashless device or coin changer/bill validator (0=infinity)
timeout-vend-result0Timeout for receiving vend result from host, after this time vend is considered failed (0=infinity)
mdb-cashless-long-pollfalseAllow long response times to POLLs for cashless device (needed for some newer NAYAX readers)
vmc-slave-address0x10Cashless device address on MDB (can be 0x60 or 0x10)
vmc-feature-level3Feature level of the cashless daemon (can be 2 or 3)
vmc-display-columns0Not implemented
vmc-display-rows0Not implemented
vmc-max-price0xFFFFADVANCED Set the maximum price for vend in base units
vmc-min-price0x0000ADVANCED Set the minimum price for vend in base units
tcp-allow-remote-hostsfalseTo allow tcp connections outside 127.0.0.1 set this to true
tcp-port31421TCP server port
tcp-client-timeout0TCP communication timeout (after this many seconds of no activity - disconnect from client) (0=infinity)
device-port/dev/ttyAMA0A port handle to communicate with mdb-usb or PI hat, it defaults to AUTOFIND
reconnect-delay30How much time to wait between reconnect tries to MDB-USB or pi hat
verbosity5Sets the verbosity level 0 to 5: 0 - Fatal | 1 - Error | 2 - Warn | 3 - Info | 4 - Debug | 5 - Trace
device-watchdogfalseRuns 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

HostDirectionDaemon
VEND,1.00\n->
Waiting for payment...
<-VEND,SUCCESS\n
RESULT,1\n->
<-RESULT,SUCCESS,1\n

Non-always-idle success vend

HostDirectionDaemon
<-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

HostDirectionDaemon
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

HostDirectionDaemon
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

MessageDescription
VEND,FAILED,INVALID_STATEFailed 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,STARTStart timeout timed out
VEND,FAILED,TIMEOUT,VENDVend approval timeout timed out
VEND,FAILED,READER_RESETFailed due to reader being reset
VEND,FAILED,VEND_DENIEDVend was denied
VEND,FAILED,ESCROW_LEVERVend was aborted because escrow lever on coin changer was triggered
VEND,SUCCESS,CASHLESSVend successful with cashless device, you MUST send either RESULT,0 or RESULT,1 after this, see RESULT command
VEND,SUCCESS,CASHVend 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

MessageDescription
STOP,SUCCESS,POST_VENDSession stopped during POST_VEND state due to host sending STOP command
STOP,SUCCESS,VENDSession stopped during VEND state due to host sending STOP command
STOP,SUCCESS,STARTINGSession stopped during STARTING state due to host sending STOP command
STOP,SUCCESS,CREDITSession stopped during CREDIT state due to host sending STOP command
STOP,FAILED,INVALID_STATENo 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

MessageDescription
RESULT,FAILED,INVALID_ARGUMENT,1Invalid argument 1 specified (not 0 or 1)
RESULT,FAILED,INVALID_STATEFailed 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

MessageDescription
STATE,{cashlessState},{coinChangerState},{billValidatorState}The state of the devices

Cashless device states

StateDescription
DISCONNECTEDMDB USB or MDB pi hat is not connected
CONNECTEDConnected to MDB USB or MDB pi hat
RESETCashless device inactive
INITCashless device setup
STARTINGEnabling the reader
IDLEReader enabled and IDLE
CREDITCard was inserted and there is credit available
VEND_REQVend request was intiated
POST_VENDVend request processed

Coin changer states

StateDescription
OFFLINECoin acceptor disconnected
RESETPerforming reset procedure
RESET_POLLCoin acceptor is being polled for Just Reset response
SETUPSetup command sent to coin acceptor
COIN_TYPEEnabling coin acceptor
ENABLED_IDLECoin acceptor enabled
CREDITCoin or multiple coins were deposited to the coin acceptor
VEND_REQVend request was intiated
POST_VENDVend request processed

Bill acceptor states

StateDescription
OFFLINEBill acceptor disconnected
RESETPerforming reset procedure
RESET_POLLBill acceptor is being polled for Just Reset response
SETUPSetup command sent to bill acceptor
BILL_TYPEEnabling bill acceptor
ENABLEDBill acceptor enabled
CREDITBill was deposited to the bill validator
VEND_REQVend request was intiated
POST_VENDVend request processed

VERSION

Syntax

VERSION

Example

VERSION

Description

Requests the daemon version

Responses

MessageDescription
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

MessageDescription
DISPENSE,1Dispense successful
DISPENSE,0Dispense 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

MessageDescription
TUBE_STATUS,FAILED,COIN_CHANGER_NOT_SUPPORTEDCoin changer is disabled by config option
TUBE_STATUS,FAILED,COIN_CHANGER_DISCONNECTEDCoin changer not connected or not initialized
TUBE_STATUS,FAILED,COIN_CHANGER_NOT_READYNo 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

MessageDescription
ERROR,SERIAL___CONN___LOSTSerial connection to the pi hat or mdb-usb has been lost
ERROR,CASHLESS_OFFLINEMDB Cashless device went offline
ERROR,COINCHANGER_OFFLINEMDB Coin changer wen offline
ERROR,BILLVALIDATOR_OFFLINEMDB 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.

Bash
Copy

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

Raspberry/Barionet or any other device that has netcat installed
Copy
MDB USB
Copy

Authorization first

Raspberry/Barionet or any other device that has netcat installed
Copy
MDB USB
Copy
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard