PX GPRS Message Specification

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

Australia

AE = Queensland (AEST)

AU = New South Wales (AEDT)

WA = Western Australia Time (AWDT)

AW = Western Australia Time (AWDT)

AC = Southern Territories (ACDT)

SA = Southern Territories (ACDT)

NT = Nothern Territories (ACST)

Pacific

NZ = New Zealand

FJ = Fiji

Europe

GB = Greenwich Mean Time (GMT)

CE = Western Europe Standard Time

North America

HA = hawaiian Standard Time (HAST)

AK = Alaskan Standard Time (AKDT)

UC = Central Standard Time (CST)

UP = Pacific Standard Time (PST)

UE = US Eastern Standard Time (EST)

UM = US Mountain Standard Time (MST)

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.

Request

~H~DeviceId~TxnRef~SwVersion~ConfigChecksum

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

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.

Authorise a Card Transaction

Request (From Device)

~A~DeviceId~TxnRef~Account~123~NZD~track2~track1~merref

Response (From PaymentExpress)

#a~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~AuthCode

Complete a Transaction

Request (From Device)

~C~DeviceId~TxnRef~DpsTxnref~123~merref

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

SMS Payment Completion

#c~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~TelcoData

TelcoData: TELCO,MSISDN,MODID eg: vodafone,64211234567,MOD05022008003858000001

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~TXTCODE

Response (From PaymentExpress)

#s~TxnRef~Success~DpsTxnRef~ReCo~ResponseText~AuthCode

Suggested Timeout is as recommended by Telecommunications provider.

Cancel a SMS Payment Transaction

Request (From Device)

~X~DeviceId~TxnRef

Response (From PaymentExpress)

#x~TxnRef~Success~DpsTxnRef~ReCo~ResponseText

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

Response (From PaymentExpress)

#d~TxnRef~Success

Success: 1 Accepted

Suggested Timeout is 10 seconds

Permit Parking Processing

Description

Sub Heading

~A~DeviceId~TxnRef~Account~123~NZD~track2~track1~merref~CVC2~TxnData1~TxnData2~TxnData3~EkUserData1~EkUserData2

Event Logging

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

~L~DeviceId~TxnRef~EventId~EventData~EventLevel

Response (From PaymentExpress)

#l~TxnRef~Success

EventId: Numeric eventid 1-99999999

EventData: EventSpecific Data string

EventLevel: Info=1, Warning=2, Error=3

Configuration Settings

ID Data
1 Cash Bag Cleared
2 Card Read Error
3 Printer Error
4 Coin Mechanism Jammed
5 Battery Low
6 Battery Critical
7 Error Condition Cleared by Technician

Software and Config Download

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

Get Config

~J~DeviceId~TxnRef

Response (From PaymentExpress)

#j~TxnRef~Success~configdata...

Success: 1 Accepted

Properties

AuthCode (Max 6 characters)

Max 6 character Acquirer supplied Authorisation Code for printing on receipt.

Account (Max 4 characters)

Reserved for future use - may be used by the device to select a range of financial accounts. Currently empty.

Amount (Max 13 characters)

Total amount. Format is d.cc where d is dollar amount (no currency indicator) and cc is cents amount. For example, $1.80 (one dollar and eighty cents) is represented as "1.80", not "1.8". A string value is used rather than the conventional Currency Datatype to allow for easy integration with Web applications. The currently Maximum value allowable is $99,999.99. Note that acquirer or card limits may be lower than this amount.

Currency (Max 3 characters)

ISO currency code - NZD, AUD, FJD, USD etc.

Configuration Settings

CAD Canadian Dollar
CHF Swiss Franc
EUR Euro
FRF French Franc
GBP United Kingdom Pound
HKD Hong Kong Dollar
JPY Japanese Yen
NZD New Zealand Dollar
SGD Singapore Dollar
USD United States Dollar
ZAR Rand
AUD Australian Dollar
WST Samoan Tala
VUV Vanuatu Vatu
TOP Tongan Pa'anga
SBD Solomon Islands Dollar
PNG Papua New Guinea Kina
MYR Malaysian Ringgit
KWD Kuwaiti Dinar
FJD Fiji Dollar

DpsTxnRef (Max 16 characters)

Payment Express transaction Reference (16 character alphanumeric). Device should store and send with any subsequent Completion message to allow PaymentExpress to generate correct completion information.

MerchantReference (Max 64 characters)

Transaction Reference. May be blank nor may contain a receipt or transaction reference (appears in merchant reference feild on reports. If left blank, TxnRef value is used for reports.

Reco (Max 2 characters)

2 character alphanumeric response. The client application should not interpret the Response Code property contents - it is provided as informational only. The Success property determines if the the transaction was successful or not.

ResponseText (output) Datatype: BSTR Max 20 characters

Max 20 character result receipt text for receipt printing (eg: DECLINED, INSUFFICENT FUNDS etc). The Response Text is associated with ResponseCode.

Success (Max 1 character)

Indicates success or failure of the transaction. A value of 0 indicates the transaction was declined or there was an error. A value of 1 indicates the transaction was approved.

Track1

Optional, but desirable, : Contents of track1 excluding start sentinel and end sentinel

Track2

Contents of track2 excluding start sentinel and end sentinel

When submitting encrypted track2 data the encrypted data sits between the ";" and "?" sentinels. Example:

;SaV_[va+tZnt1111=FG5Gv-.wM:Ypt#s].n01?

TxnRef (Max 16 characters)

1-16 character alphanumeric transaction reference. Generated by Device. Payment Express will respond with the same TxnRef. Should be unique for outstanding/unconfirmed messages. Suggest counter from 1-999999, reverting to 1 when 999999 is reached.