Message Format

All messages are printable ASCII (ascii hex value 0x30 thru 0x7f inclusive) with the exception of the delimitor.
All messages from PaymentExpress start with a "#" character.
All messages from Device to PaymentExpress start with a "~" character.
All messages end with a (0x0d) character.
Absolute maximum message size if 1024 bytes per delimited message, including delimitor.
"~" character is reserved for use as a data field delimiter.

If it becomes a requirement to include "~" within a data field, the protocol could use a preceding escape character (eg: 0x06). Not currently implemented or needed with messages.

DeviceId is present for every message from Device. It has following format: XXXXnnnn-CC

XXXX is customer account. 1-4 alpha characters. If fewer than four characters, a "_" follows (eg: DEV_0001). nnnn is a numeric device number. CC is locale. Locale determines timezone used when returning timestamps.

The 1st field immediately following the # indicates the message type following.

Device should not assume that the number of data field is fixed. For a given message (eg: Auth), additional fields can be added to extend payload of the message for newer device software revisions, but earlier device revisions should be able to handle newer revision messages, just ignoring the additional fields.

Time Zones/ Locale

Hello Message

May be sent as often as required by the device.

PaymentExpress will respond without delay echoing the TxnRef value and providing the current time including day of week. The DeviceId supplied by the meter is used to determine the timezone and the time supplied is set to the correct timezone for the meter.

~H~DeviceId~TxnRef~SwVersion~ConfigChecksum<CR>

Swversion is version of software in device. Max 16 characters alphanumeric, case sensitive. Configchecksum is checksum of current XML config for meter. This checksum will be used by the host to determine if a new config needs to be downloaded.

Response

~h~TxnRef~TimeStamp~NewSwVersion~ConfigReady<CR>

TimeStamp is day of week yyyy mm dd hh mm ss
eg: 520060105220401 = Thursday, 5 Jan 10:04:01pm

NewSwVersion is non blank if a new software release is available for download. ConfigReady is 1 if a new config is available for download, 0 if config is current.

Credit Card Processing

The meter should authorize a transaction for the maximum amount to be charged or the exact amount to be charged (if known when the authorisation is submitted. An approved authorisation responds with a DpxTxnRef which may be used by a subsequent Completion to force the card to be charged. If, after successful authorisation, a ticket cannot be supplied perhaps due to hardware malfunction, the completion is simply not sunbmitted and the temporary lock on cardholder funds for the auth amount is released after a few days with no charge being apparent to the cardholder.

Authorize a Card Transaction

Request (From Device)

~A~DeviceId~TxnRef~Account~123~NZD~track2~track1~merref<CR>

Response (From PaymentExpress)

#a~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~AuthCode<CR>

Complete a transaction:

Request (From Device)

~C~DeviceId~TxnRef~DpsTxnref~123~merref<CR>

The DpsTxnRef used to complete the transaction is the same DpsTxnRef as received by the device in response to an authorisation. If no response is received, the transaction should be repeated with identical data until a positive response is received. PaymentExpress will ensure no duplicate transaction is created based on DpsTxnref.

Response (From PaymentExpress)

#c~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~AuthCode<CR>

SMS Payment Processing

Very similar to credit card payment set. Use "S" command instead of Authorize. If user cancels or meter determes other reason for cancellation, meter should not send the completion. To apply the charge (after receipt printed etc), device sends completion in same manner as for credit card.

Initiate a SMS Payment Transaction

Request (From Device)

~S~DeviceId~TxnRef~Account~Amount~merref<CR>

Response (From PaymentExpress)

#s~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~AuthCode<CR>

Suggested Timeout is as recommended by Telecommunications provider.

Cancel a SMS Payment Transaction

Request (From Device)

~X~DeviceId~TxnRef<CR>

Response (From PaymentExpress)

#x~TxnRef~Success~DpsTxnRef~ReCo~ResponseText<CR>

The cancel transaction can be used to abort an in progress SMS Payment Authorisation. It will be immediately responded to by the Payment Express. If a SMS Payment Authorisation was in progress, the Cancel response ("x") will be followed by a declined payment authorisation ("s").

Cash Payment Processing

Very similar to credit card payment set. Use "D" command instead of Authorize. If user cancels or meter determes other reason for cancellation, meter should not send the completion. To apply the charge (after receiot printed etc), meter sends completion in same manner as for credit card.

Record a Cash Payment

~D~DeviceId~TxnRef~Account~Amount~merref<CR>

Response (From PaymentExpress)

#d~TxnRef~Success<CR>

Success: 1 Accepted
Suggested Timeout is 10 seconds

Event Logging

Send an Event (eg cash bag clear or printer fault etc) to central systems

~L~DeviceId~TxnRef~EventId~EventData~EventLevel<CR>

Response (From PaymentExpress)

#l~TxnRef~Success<CR>

EventId: Numeric eventid 1-99999999
EventData: EventSpecific Data string
EventLevel: Info=1, Warning=2, Error=3

Success: 1 Accepted
Suggested Timeout is 10 seconds

Software and Config Download

Used to retrive configuration or to initiate a software download to the device

Get Config

~J~DeviceId~TxnRef<CR>

Response (From PaymentExpress)

#j~TxnRef~Success~<xml>configdata...</xml><CR>

Success: 1 Accepted

Properties