Skip to main content

Architecture

Hii Mobile Payments consists conceptually of the following parts:

  • a Unified Mobile Payment API (UMP API) for requests and responses related to mobile payment flows
  • several Mobile Payment Connectors, one specific service for each mobile payment service provider that is supported

With Hii Mobile Payments, a POS system can be integrated once with the Unified Mobile Payment API and via that single integration switch between any supported PSP without any modification of the POS.

System context​

System context

Containers​

Our preferred method of integration is with an asynchronous event-driven API, for example using webhooks.

Containers

Components​

Components

The components view shows the internals of a Mobile Payment Connector. It shows that a Mobile Payment Connector service consists of the following

  • A spec-first schema used for all validation. There's no additional DTOs needed for validation and processing
  • A Mobile Payment specific integration module

APIs​

The following APIs are part of Hii Payments:

  • Unified Mobile Payment API
    • API used by Checkout Engine and potentially other POS systems to integrate with once to be able to use any existing PSP connector. This API is available as a Open API. The message format is defined as JSON schema.
    • This API is supported by every Mobile Payment Connector.

IDEALS​

Hii Retail services adheres to the IDEALS principles in microservice architecture. This section covers how the design choices in Hii Connect - Mobile Payments fulfills the IDEALS.

Interface segregation​

The service will offer one type of APIs

  • Open API

The Open APIs offer resources to initiate payment flows in a callback fashion where the response is sent to an outbox service from where it can be pooled.

Deployability​

  • The solution is designed as a serverless, independently releasable, testable and scalable service.
  • Best practices from the cloud platform will be followed
    • Favor serverless (Cloud Run)
    • Infrastructure as code

Event-driven​

The solution architecture is event-driven.

  • All execution occurs within the request or event-scope. The service requires no CPU cycles outside of the request context.
  • Idempotency is an open topic for discussion and need to be analyzed more.

Availability over consistency​

The system depends on external PSPs which are typically stateful and focused on consistency. The Hii Mobile Payments attempts to hide all of the messy state management, that is common in the external PSP solutions.

Loose-coupling​

This service has no dependencies on other services. but is essential for our Checkout Engine to fulfill payments.

Single responsibility​

The single responsibility of the service is to process mobile payment flows for mobile app payments. Every Mobile Payment Connector is deployed as a separate micro service.

General considerations​

General Hii Retail design considerations as applied to the PSP Connectors.

Multi-tenancy​

The Mobile Payment Connector services are multi-tenant.

  • All payment flows runs in a tenant scope.
  • Checkout configuration and webhooks are isolated by tenant

Auditing​

Security​

  • All ingress and egress uses TLS
  • All APIs are secured using either
    • Hii Retail IAM (for users)
    • Workload identity
    • OCMS
  • Webhook endpoints are secured using basic authentication
  • Data is encrypted at rest using Google managed keys

GDPR​

The service will use the phone number as the primary identifier. The phone number is considered personal data. The service will not store any personal data. The service will not use any personal data for any purpose other than processing payments. The service will mask the phone number in logs and it will not be possible to search for a phone number in logs. No database records will be created with the phone number.

Data mesh​

Not planned.

Internationalization​

The service will support i18n and l10n.

  • All date-time fields are UTC "Zulu" time
  • All numbers are proper numbers
  • Produced receipt texts are translated as per required financial legislation

The Mobile Payment Connectors will support translations of PSP Connector specific texts as required for each individual integration. The Mobile Payment Connectors shall integrate with any future translation service in Hii Retail. Until available, the Mobile Payment Connectors will include translations as Java native language resource bundles as that is the minimum development and design effort.