HiiRetail Payment Services
This document explains the purpose and usage of the HiiRetail Payment Services for developers and professional services colleagues. These services help determine and execute payment transactions for HiiRetail customers, contributing to the overall payment processing efforts.
Overview
There are two main categories of transactions that the HiiRetail Payment Services processes:
- Card Payment Transactions
- Gift Card Payment Transactions
The HiiRetail Payment Services comprises several components:
- Payment Plugins - Payment Plugins are used to integrate Checkout Engine or other POS Systems with the Payment Service.
- Payment Router - The Payment Router is responsible for routing payment requests from the POS System to the appropriate PSP Connector. The payment router knows which PSP Connector to use based on a configuration stored in a dedicated datastore. Only the PSP Connectors are updating the configuration by pushing events through Pub/Sub.
- PSP Connectors - PSP Connectors are microservices that handle the actual payment processing. Each PSP Connector is responsible for a specific payment provider, such as Adyen, Nets, Softpay, Viva, or WIPay. The PSP Connector is responsible for processing the payment request, handling the payment response, and updating the payment status in the Payment Service. The payment response is then dispatched to the Outbox Service and/or the Pub/Sub Service.
- Outbox Service - The Outbox Service listens to events from the PSP Connectors and stores them in a database waiting for the POS System to pick them up by polling.
- Pub/Sub Service - The Pub/Sub Service receives events from the PSP Connectors and publishes them to a Pub/Sub topic. The POS System can then subscribe to the Pub/Sub topic to receive the events.
- UI Console - The UI Console offers an intuitive user interface for configuring the PSP Connector. Accessible to any registered user with the appropriate permissions, it enables the definition of environments, registration of provider callback URLs, and, most importantly, onboarding of payment devices to specific stores and tills. This data is sent to the PSP Connector for storage in the database and subsequently forwarded to the Payment Router Service, ensuring payment requests are directed to the correct PSP Connector.
- Terminal Admin Service - The Terminal Admin Service is responsible for managing the configuration of physical payment terminals. Its features are highly dependent on the payment terminal model and the payment provider.
- Availability Service - The Availability Service ensures the reliability of payment services by performing periodic health checks every few minutes. This helps verify that requests are processed correctly throughout the payment flow. The requests initiated by the Availability Service are sent by the PSP Connector to a mock server, which simulates the third-party provider.
The HiiRetail Payment Service is designed to be highly available, scalable, and secure. It is built on a microservices architecture, with each component being independently deployable and scalable. The service is designed to handle high transaction volumes and provide real-time payment processing capabilities.
PSP Connectors operate independently and can be scaled horizontally to accommodate increased transaction volumes. Even in case of downtime in one PSP Connector, the others remain fully operational. However, the Payment Router Service and Response Services (Outbox and Pub/Sub) represent single points of failure—if either becomes unavailable, the entire system is impacted.
Integration & Usage
Developers can leverage these services to enhance payment processing strategies in HiiRetail environments through REST APIs:
- Unified Payment Request API (https://developer.hiiretail.com/api/unified-payment-card-requests-api) - provides a unified interface for submitting payment requests to the PSP Connectors
- Unified Payment Response API (https://developer.hiiretail.com/api/unified-payment-card-responses-api) - provides a unified interface for receiving payment responses from the PSP Connectors
- Unified GiftCard Payment Request API (https://developer.hiiretail.com/api/unified-payment-giftcard-requests-api) - provides a unified interface for submitting gift card payment requests to the PSP Connectors
- Unified GiftCard Payment Response API (https://developer.hiiretail.com/api/unified-payment-giftcard-responses-api - provides a unified interface for receiving gift card payment responses from the PSP Connectors
Each PSP Connector implements the generic UP API & UGC API, but they also have specific APIs for each payment provider.