Cloud Connector

Cloud Connector allows you to connect your POS with your device by creating a virtual connection in the cloud. Cloud Connector is agnostic to the content of the data that is sent from the POS to the device and vice versa, using secure websockets for transporting the messages. Designed with scalability in mind, Cloud Connector allows the deployment of the same solution with or without Cloud Connector, as devices migrate from a local communication approach to a cloud solution across the terminal estate.

Prerequisites

Before using the Cloud Connector service, the following expectations must be met:

• Each device must be provisioned and enabled in PPaaS.

• The PPaaS client must:

  • Subscribe to the Cloud Connector service within the Retail API Service Domain

  • Enable the service for the merchant aggregator as well as the merchant

• Additionally, if you are using the Tetra UPP application, the device must be loaded with the appropriate certificates to support secure WebSockets (WSS) as a client.

Authentication

Authentication from a POS system to PPaaS is achieved using client credentials. You can retrieve them by:

• Creating separate credentials for each POS device associated with each store. Credentials will then be valid only for devices associated with the store.

• Creating a developer application at the higher-level scope of Merchant Aggregator (MA). Credentials will then be valid for all devices of this MA.

Tips to get you started with authentication:

• The authentication endpoints are prefixed by "auth", for example: https://auth.qa.ppaas.tech.

• Client services will tell you the values {your-domain} and the {baseUrl} for your region as part of the onboarding process.

• Authentication is based on the OAuth 2.0 client credentials grant type, intended for machine-to-machine authentication.

• TLS is required for all connections.

Client Credentials Creation

Store POS Credentials

Create and retrieve your client credentials as per below:

1. Login to the PPaaS client portal as a Merchant user.

2. Create a store.

3. Create a POS.

4. Gather the client id and key for your POS.

Developer Application Credentials

Create and retrieve your client credentials as per below:

1. Login to the PPaaS client portal as a Merchant Aggregator user.

2. Create a Cloud API Application.

3. Under API, assign the "Retail API" service to your app.

4. Under Credentials & Security > Credentials, enable "Client Credentials Grant".

5. Under Credentials & Security > Roles, assign the "Point-of-sale Terminal" role to your app.

6. After saving your app configuration, gather the client id and key for your POS.

Authentication for the POS application

To authenticate the POS application with PPaaS, call the below API with the client credentials provided during the application registration process. POST https://{baseUrl}/oauth2/v1/{your-domain}/token

Authentication for the Device application

1. Gather the values for the POS client credentials, i.e. {client id} and {key} as described earlier.

2. Edit the PBT file on the device to define the properties relating to the ws_client. Set your {client id} and {key} values as a json extract for the custom_registration_data property: custom_registration_data: “{‘client_id: {client id}, ‘client_secret’: {key}}” Example: custom_registration_data: "{\"client_id\":\"c1d130d2-9dc0-4b0a-89f4-cd8f25d52afd\",\"client_secret\":\"JFc9QpS61D5lKIwv0fWPmigdy2sEinl3\"}"

3. Provide the Cloud Connector’s Registration Server endpoint using the ep_register_url property: ep_register_url: wss://{base-url}/cloud-connector/v1/device-listener

4. Ensure that the UPP/USI app is expecting to use TLS and hence secure WebSockets: enable_ssl: 1

5. Provide the details of the certificates, i.e. the name of the Certificate Authority and the location of the pem file on the device:

ssl_profile_name: “INGETRUST” ssl_profile_crt: {location of the pem file on the device}

Build your integration

Once you have successfully onboarded your merchants and devices into PPaaS and you have set up the POS application and device to authenticate with Cloud Connector, these are the steps to connect a POS to a device. Clients who have previously integrated their POS to UPP and USI and are now looking to migrate to the Cloud Connector service will recognize that PPaaS performs the role of both the WebSocket Registration Server and WebSocket Connection Server from the device perspective.

Important: Note the first 4 steps are included only for completeness, but they are performed by the app on the device in dialogue with PPaaS. Your integration effort begins at Step 5.

1. The device establishes a secure WebSocket connection to the below URL: wss://api.qa.ppaas.tech/cloud-connector/v1/device-listener/ .

2. The device sends a message to the registration endpoint hosted by PPaaS which is acting as the Registration Server.

3. PPaaS returns a connection URL for the device to connect to and a JWT to act as an authorization bearer token for the next call. The WebSocket established at step 1 is disconnected.

4. The device establishes a new secure WebSocket connection to the connection URL. The JWT is passed as authorization header to authorize the connection.

5. The POS gathers an access token using the client id and secret from the PPaaS Application.

6. The POS establishes a WebSocket connection to this URL with the access token as bearer token: wss://api.qa.ppaas.tech/cloud-connector/v1/pos-listener.

7. The POS makes a request to PPaaS to claim a device’s session using the terminal serial number (tsn).

8. PPaaS returns a session URL for POS to claim the device session.

9. POS connects to the PPaaS URL. At this point the device has established a secure WebSocket connection to PPaaS.

10. Messages can flow from POS to device.

11. Messages can flow from device to POS.

Register your device with PPaaS

To integrate with the Cloud Connector solution, the Terminal Application must connect with the WebSocket Device Listener service. For successfully connecting with the Device Listener service, the device will need to pass the token retrieved during authentication.

Upon successfully sending the request, the device application will receive a response with a status code. For compatibility with NAR payment applications and where the device is an Ingenico device, the tsn (terminal serial number) value can either be a fully qualified identifier including the make and model or only the serial number.

Claim device session with pos-listener

To establish a connection between the POS and the device, the POS needs to claim a session with a specific device using the POS Listener service. For successfully connecting with the POS Listener service, the POS will need to pass the token retrieved during authentication. If the request is successful, a device session would be established with the POS for which you can retrieve session url.

Create a websocket connection for a POS

In order to complete the device claim process, the POS will also need to establish a WebSocket connection with the session URL provided by the Cloud Connector.

Loss of connection

The device application design must consider implementing strategies to handle scenarios where connection to the cloud is lost.

Larger customers have solved this issue by investing in 2, 3, or 4 levels of redundancy for connectivity to the cloud. For smaller merchants, a possible solution could be to use hot spots.

When connectivity goes down, customers still want to be able to transact and expect features like Store And Forward (SAF). To accommodate this type of situation, the Ingenico device (or application) must support one of the following features: - A standalone mode which allows to associate the key in the transaction details. - A connectivity fallback mode which allows the ISV or POS to still interact with the Ingenico device without the need for Cloud Connector.

In this situation, the Ingenico device can be configured to detect the lost connection to PPaaS and react accordingly. For example, the Ingenico device can automatically switch from a client on the PPaaS Cloud Connector to a server on the local network. This way, an ISV or POS on the local network can still access the Ingenico device.

Frequently Asked Questions

• Does Cloud Connector affect a customer or an Ingenico payment applications EMV L3 certification?

No, it does not. The communication channel used between the POS and the terminal is not part of EMV L3 certification.

• Is this solution available for Telium2 devices using RBA, UIA, or some other Telium2 application?

No, it is not. The solution is available for Tetra and Axium devices using any of Ingenico’s WebSocket and JSON based APIs.

• What happens if PPaaS or the Internet Service Provider (ISP), is not available?

Typically, this would mean the POS cannot connect to the terminal, therefore, the POS cannot drive a transaction. As part of a second phase of the Cloud Connector solution, Ingenico will develop logic on the terminal side to allow for a local connection (instead of trying to connect to PPaaS) when PPaaS or the ISP is down. The POS would then need to implement some simple logic to switch to a local connection for the device instead of a PPaaS connection.

• Can devices in the field be updated to use the Cloud Connector?

Yes, downloading a configuration file to the terminal and rebooting it can allow a terminal to connect to Cloud Connector.

• Does the Cloud Connector support firmware updates?

No, customers should use Estate Manager for firmware updates.

• Can a customer develop their own Cloud Connector?

Yes, they can, and some have. The challenge is our customers would rather spend their time working on other features/functions for their merchants etc. Additionally, the initial cost of development for customers is very high (hardware costs, development costs, etc.). Our advantage here is that we can develop it once for many customers and maintain it on their behalf.

• Can browser-based tools by used to implement Cloud Connector?

No, right now this is not supported. Please contact PPaaS Client Services if you are interested in using this feature.