VCloud Payment API Overview

The VCloud payment API allows POS vendors to process EFTPOS terminal payments via a cloud-based API.

Transaction Processing Models

POS Vendors can choose between the Web Integration or the Basic Integration methods to enable VCloud payments on the POS Application. Basic Integration is feature limited and should only be used if Web Integration is not possible.

Web Integration: The Extended API 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.

Basic Integration: The Basic Integration method performs an EFTPOS transaction within a single API call. There is no ability for the user (e.g. sales assistant) to see any intermediate prompts that indicate what the terminal is doing (e.g. "Present Card" etc). This method is not very sophisticated and more suited to situations where Web Integration (above) is not possible.

Integration Basics

All API operations are accessed via HTTPS and include JSON formatted request or response data.

Definitions

POS Service: This is the name of the POS product, service, or company. This name will be assigned to the POS developer before the service goes live in production. To get a POS Service name contact Verifone support.

Merchant ID: This is the unique identifier of a merchant within the POS Service. It is generated by the POS Application.

Register ID: This is the unique identifier of a register (or lane) within the POS Service. It is generated by the POS Application and must be unique across all merchants of the POS Service. If the register ID is not naturally unique across all merchants, then developers should prefix the merchant ID to the register ID.

Reference ID: This is the unique identifier of a transaction submitted by the POS Application. It is generated by the POS Application and must be unique for all transactions of the service. If the reference ID is not naturally unique, then developers should prefix additional data to it to make it unique.

URLs for Testing and Production

Terminal Pairing

Before a terminal can be used it must be paired with a register. This can be done in several ways:

INLINE: Inline pairing means pairing 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. NOTE: Inline pairing is not supported when basic integration is used.

WEB INTEGRATION: Web integration pairing means using the web integration method to pair. The pairing page is intended to be displayed within an iframe inside a POS Application page. This method has the best user experience and works well for web based POS applications.

API INTEGRATION: API Pairing means using the basic integration method to pair. See the basic integration API for more details.