Web Integration

Overview

The Web Integration method performs an EFTPOS transaction within a web page. The web page is intended to be displayed within an iframe inside a POS Application page. When the transaction is processing the user (Sales Assistant) will be able to see the progress of the transaction. When the transaction completes the VCloud web page will use the HTML5 postMessage() API to let the POS Application know the result of the transaction. This method may be more involved but the user experience is much better.

Please check out the demo to get an idea of how it looks and works.

Starting a Transaction

A transaction can be started by doing a HTTP GET request to the required end point:

webint/purchase/{pos_service}

webint/refund/{pos_service}

The GET request must also have several query values set:

Argument	Description
merchant_id	[Mandatory] The unique ID of the merchant (or retailer)
register_id	[Mandatory] The unique ID of the register (or lane)
reference_id	[Mandatory] The unique ID of the transaction
amount	[Mandatory] The decimal amount in dollars (e.g. 1.95)
cash_amount	The cash amount, if applicable
mm_account_idx	The multi-merchant account index, if supported
pos_prints_receipt	Set to true if the POS should print the receipt and not the terminal - otherwise leave empty
prevent_manual_recon	Set to true to treat any unknown transaction result as a FAILURE (typically used for vending applications) - otherwise leave empty

For example, https://vcloud-dev.alt-payment.com/webint/purchase/TESTPOS?amount=1.00&cash_amount=0.00&reference_id=1639626878908&register_id=REGISTER1&merchant_id=MERCHANT1

The GET request will then return a full HTML page, with JavaScript, which will process the transaction and then let the parent page (or opening window) know the result of the transaction by using the postMessage() JavaScript function.

Completing a Transaction

When the transaction is complete JavaScript on the page opened will use the postMessage() method to send a simple JSON object back to the parent window. This object will contain several fields:

Field	Content
reference_id	The unique ID of the transasction
result	The result of the transasction (SUCCESS, FAILURE, CANCELLED, NOCONNECTION, or UNKNOWN)
final_message	The result of the transaction in human readable form (optional)
receipt	The receipt data for the transaction, if available
total_amount	The total amount of the transaction including tip and surcharge amounts that may have been added.
cash_amount	The cash amount, if available
tip_amount	The tip amount, if available
surcharge_amount	The surcharge amount, if available
online_status	Indicates if the transaction was processed ONLINE or OFFLINE. May be not present or null if not available.
card_type	The card type, if available

Pairing Terminals

If you are using the web integration method to process transactions you have several options to implement pairing:

INLINE: Pairing will occur when the first transaction for a register is started. This is convenient but won't allow the register to be paired to another terminal. POS developers don't need to do anything to support inline pairing, it will be used automatically if the register is not paired.

WEB INTEGRATION: Web integration pairing means using the web integration method to pair. To start pairing using this method you'll need to navigate to the endpoint /webint/config/{pos_service}/{api_key} to start the process in the web browser. This method has the best user experience and works well for web based POS applications. The web integration demo allows you test out this pairing method. This method supports the use of query arguments to supply the merchant ID (merchant_id), the register ID (register_id), and merchant name (merchant_name). These query arguments are optional - if omitted then the user will be prompted for them.

API INTEGRATION: You can also use the basic integration API to pair terminals. See the basic integration API for more details.

Sample HTML

Sample HTML for the Integration Demo can be found here.