Check the Retail API reference here.
For a POS software to interface with a payment device and execute payment within a payment device, PPaaS provides the PPaaS Retail APIs. The PPaaS Retail APIs implement the Nexo Retailer protocol v5 international standard (https://www.nexo-standards.org/standards/nexo-retailer-protocol) with JSON message format. PPaaS Retail APIs are cloud-based APIs, which provide the following benefits:
Seamless integration with Cloud-based POS solutions.
Easier communication between POS and payment devices compared to local connectivity (for example, wired connectivity).
Enabling flexible configuration of POS and payment devices accross the store. This provides the ability to have a tablet acting as a POS, from which a staff member selects which payment device to use for the payment process.
The Retail APIs allow to send requests to a payment device as shown in the below diagram:
The functionalities supported by the latest version of the Retail APIs are:
Listing available payment devices in the store where the POS is registered along with the list of supported payment methods.
Managing a session from a POS to a payment device within a merchant store.
Triggering sale transactions specifying the amount and the payment method.
The Retail APIs are able to work with any number of payment devices registered in PPaaS as long as the payment device is compatible with PPaaS, i.e. having a payment application which supports the PPaaS Retail APIs.
Prerequisites
Before using the Retail APIs, the following expectations must be met:
POS must have an Internet connection.
The PPaaS Client must subscribe to the to the Retail API PPaaS service.
The payment device and the POS must be registered into PPaaS.
The software within the payment device must be compatible with the Retail APIs.
Build your integration
The below sequence diagram describes a typical Cloud Retail API interaction between the POS, PPaaS, and the payment device.
POS Registration & Authentication
For security reasons, it is required to have the POS registered into PPaaS for each merchant store. This step has to be performed directly by the merchant in the PPaaS portal for each of its stores. The registration process will assign a unique application ID and secret per POS. This value pair must be configured in the POS solution that will authorize the POS to trigger requests to payment device located in the same store (via the getToken API). This mechanism allows only a legitimate POS to send requests to a payment device in a given store. It also allows to easily deregister a POS in a given store without an impact to any other POS in the same store or elsewhere.
It is the responsibility of the POS software provider to properly secure the application secret.
In all-in-one configuration cases, a payment device runs both the payment and the POS applications. The security is then managed the same way as for any other PPaaS service accessed within a payment device, i.e. via Mutual Transport Layer Security (mTLS).
Payment devices integrated with Retail APIs can still be used standalone with the POS.
Tutorial: Register a POS in PPaaS
Although it is generally the role of the merchant to register the POS, for development purpose, you need to register at least one POS into the system. Once a POS is registered, an Application ID and Key are auto created for the respective POS.
To add a POS to a store:
From the STORES tab select the new store that you created or select a store for which you want to attach a POS.
Navigate to the POINTS OF SALE tab, click +ADD POINT OF SALE.
On the New point of sale section, enter the Name and Reference fields.
Click Save. The Point of sale information is now displayed, including the Application ID and Key.
Use the Application ID and Key details corresponding to the POS to set it up. You can easily view or copy the details using the icons in the Application ID and Key fields.