Supported Transaction Types
Card Purchase
This function requests the Payment Acceptance Device to initiate a purchase transaction for a specified amount.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Purchase, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.Purchase | Yes | |
| AmountTotal | 500 | The purchase amount | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
Card Refund
This function requests the Payment Acceptance Device to initiate a refund transaction, refunding the previous Card Purchase transaction.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Refund, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.Refund | Yes | |
| AmountTotal | 500 | The refund amount | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number (regardless of the fact that this is a refund). The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
QR Purchase
SmartConnect supports a generic QR code interface, that can process transactions for a number of different gateways (i.e. WeChat Pay, Alipay, closed loop payment systems, etc).
From the point of view of the POS, this transaction is identical to a Card transaction, but should be requested explicitly and ideally under a separate Payment Type (i.e. have its own "button" in the POS interface), or have another means to track QR purchase totals separately from Card purchase totals, as they will need to be reconcilled differently.
Once a QR transaction is initiated, the Payment Acceptance Device will display a QR code on the screen, and once that code is scanned by a compatible app - SmartConnect will handle all the back-end communication to the appropriate gateway.
The Transaction request will return a structurally identical response to a Card transaction.
SmartConnect supports two different "modes" of QR transaction (and two different transaction types):
- QR Code displayed on the device - where the consumer scans the QR code with their smartphone app (the transaction type is
QR.Merchant.Purchase); - QR Code scanning mode - where the consumer will display the QR code to the merchant on their smartphone app, and the merchant will use the payment device to scan this code, or input it manually if there is no scanner available (the transaction type is
QR.Consumer.Purchase).
QR.Merchant.Purchase is the preferred mode and this transaction type should always be implemented, whereas the QR.Consumer.Purchase is optional.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as QR.Merchant.Purchase (or QR.Consumer.Purchase), and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | QR.Merchant.Purchase | Yes | |
| AmountTotal | 500 | The purchase amount | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
QR Refund
This function requests the Payment Acceptance Device to perform a refund transaction, refunding a previous QR transaction.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as QR.Refund, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | QR.Refund | Yes | |
| AmountTotal | 500 | The refund amount | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number (regardless of the fact that this is a refund). The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
Purchase + Cash
This function requests the EFTPOS Terminal to initiate a purchase transaction with a cash-out amount.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.PurchasePlusCash, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.PurchasePlusCash | Yes | |
| AmountTotal | 500 | The total amount of the transaction, including the cash-out amount | Yes |
| AmountCash | 100 | Cash portion of the AmountTotal | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will to the currency configured on the Payment Acceptance Device.
Cash Advance
This function requests the EFTPOS Terminal to initiate a cash-out only transaction.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.CashAdvance, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.CashAdvance | Yes | |
| AmountTotal | 500 | The cash-out amount | Yes |
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
Authorise
This function requests the EFTPOS Terminal to initiate an Authorise transaction, to reserve funds in the cardholder’s account.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Authorise, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.Authorise | Yes | |
| AmountAuth | 500 | The amount to authorize | Yes |
| TransactionReference | AUTH01 | Reference string; alphanumeric, up to 8 characters | No |
The TransactionReference field is used to look up and retrieve the original auth information when finalising. If the TransactionReference matches an existing stored transaction, the EFTPOS Terminal will prompt whether to continue. If YES, the existing auth transaction will be updated; if NO, the transaction will be cancelled. In all cases, the value used for the transaction is returned in the result message (for accepted transactions) and that value must be used when finalizing.
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
Finalise
This function requests the EFTPOS Terminal to finalise an auth transaction, debiting funds from the cardholder’s account.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Finalise, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Card.Finalise | Yes | |
| AmountFinal | 500 | The amount to debit | Yes |
| TransactionReference | AUTH01 | Reference string; alphanumeric, up to 8 characters | Yes |
The TransactionReference field needs to match the reference from the Authorise function, either supplied or returned as the result.
Note: The amount is provided in cents - so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.
Logon
This function requests the EFTPOS Terminal to perform a logon operation with the Acquirer.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Logon, and there are no additional parameters.
Note: Smartpay EFTPOS Terminals perform the Logon operation automatically whenever it is necessary, and most integrations have no reason to implement this function explicitly. It will remain in the specification mostly for legacy purposes, and some POS systems use the Logon function as a way to “test” if the connection (both to the Terminal and to the acquirer) work.
Settlement Inquiry
This function requests the EFTPOS Terminal to perform a settlement inquiry operation with the Acquirer.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Settlement.Inquiry, and additional parameters are:
| Parameter Name | Example Value | Comment | Mandatory |
|---|---|---|---|
| TransactionType | Acquirer.Settlement.Inquiry | Yes | |
| Date | 20180413 | The inquiry date (YYYYMMDD) | No |
Settlement Cutover
This function requests the EFTPOS Terminal to perform a settlement cutover operation with the Acquirer.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Settlement.Cutover, and there are no additional parameters.
Reprint Receipt
This function is used to reprint the receipt of the last financial transaction on the Payment Acceptance Device.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Journal.ReprintReceipt, and there are no additional parameters.
Get Terminal Status
This function requests the current status of the EFTPOS Terminal.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Terminal.GetStatus, and there are no additional parameters.
Note: Legacy integrations migrating to SmartConnect tend to call this function prior to initiating any other transacting type. This is not an approach we recommend to check whether the terminal is paired or ready to accept other transaction types. If the intent is to submit a Purchase transactions, the recommend approach is to only send one request (for the Purchase transaction) and handle any eventual errors, rather than doing two API calls.
Terminal Read Card
This function reads the card PAN from the EFTPOS Terminal.
Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Terminal.ReadCard, and there are no additional parameters.
The full card PAN will be in the CardPan field of the response (which normally contains only the last four digits).
Note: this function will only work for epay cards, under a specific BIN range, it cannot be applied to any other type of card – swiping another card on the EFTPOS Terminal will result in an error, and the Transaction Result will be CANCELLED.