Skip to main content

Payment Service

Service Type: Broker Platform REST Microservice / Payment Orchestration Layer Language: Kotlin / Micronaut Framework Database: PostgreSQL (owned) Messaging: No direct Kafka integration identified External Integrations: DEUSS Core Payment Service, Company Service, Payment Service Provider (PSP), Validation App Status: Implemented (v0.1)

Overview​

Broker Platform Payment Service provides the payment-facing API for users, companies, the external Payment Service Provider (PSP), and the Validation App. It maintains the local payment view required by the Broker Platform, retrieves payment data from DEUSS Core Payment Service, exposes payment instructions to senders, stores Payment Provider data, and coordinates AML-related workflows. The service does not appear to be the authoritative source for blockchain payment state. Blockchain-related payment processing is delegated to DEUSS Core Payment Service.

Business Responsibilities​

  • Payment Information Retrieval — Retrieve payments associated with a wallet or market deal
  • Payment Instructions — Provide senders with the Payment Provider IBAN, amount, currency, and payment reference
  • Payment Status History — Pass through payment status history from DEUSS Core Payment Service
  • Bond Payday Queries — Retrieve scheduled coupon and principal payment dates
  • Payment Synchronization — Fetch and locally store payment information from DEUSS Core Payment Service
  • Payment Provider Coordination — Store Provider IBAN information and process Provider callbacks
  • AML Workflow Coordination — Initiate AML checks and receive AML results
  • Payment Marking — Allow payment records to be marked as paid in the local service
  • Payment Access Control — Restrict payment visibility based on wallet and company-related permissions

Owned Data​

The service owns a local payment representation.

Main Entities​

  • payment — Local payment record identified by the Payment Provider transaction reference
  • receiver_wallet — Receiver wallet and receiver IBAN data associated with a payment

Payment Attributes​

The local payment record includes:

  • Transaction reference
  • Payment type
  • Sender wallet and IBAN
  • Receiver wallets
  • Payment Provider IBAN
  • Payment amount
  • Payment price
  • Currency
  • AML status
  • Local marked_as_paid flag
  • Creation and update timestamps

Payment Types​

The data model supports:

  • PURCHASE_SENDER
  • PURCHASE_RECEIVER
  • PURCHASE (legacy)
  • SETTLEMENT_SENDER_PRINCIPAL
  • SETTLEMENT_RECEIVER_PRINCIPAL
  • SETTLEMENT_SENDER_COUPON
  • SETTLEMENT_RECEIVER_COUPON

AML States​

  • NEW ,REQUESTED ,OK ,DENIED ,EXPIRED The service stores a local operational view of payment data. Core payment and blockchain state remain owned by DEUSS Core Payment Service and the blockchain/indexing layer.

Inbound Interfaces​

Public Payment REST API​

The public API is defined in payment-public.openapi.yaml.

EndpointMethodPurpose
/payments/{wallet}GETRetrieve payments for a wallet with filtering, sorting, and pagination
/payments/deal/{dealId}GETRetrieve the payment associated with an on-chain market deal
/payment/{paymentReference}/paymentInstructionsGETRetrieve payment instructions for the sender
/payment/{paymentReference}/statusHistoryGETRetrieve payment status history through DEUSS Core Payment Service
/payment/{paymentReference}/setMarkAsPaidPUTSet the local sender-paid flag
/bonds/{isin}/paydaysGETRetrieve scheduled bond paydays

Payment Provider and Validation App API​

The partner-facing API is defined in payment-partners.openapi.yaml.

EndpointMethodCallerPurpose
/payment/{transactionReference}/amlPOSTPayment ProviderStart AML processing and obtain the relevant company IBAN
/payment/{transactionReference}/aml/resultPATCHValidation AppSubmit the AML result
/payment/{transactionReference}/instructionsPATCHPayment ProviderStore the Provider IBAN and confirm payment-provider-side receipt

These endpoints use Basic Authentication credentials configured for external partner access.

Security​

The service supports:

  • Propagated Authorization headers for internal service calls
  • Basic Authentication for Payment Provider and Validation App callbacks
  • Public API authorization based on the authenticated user and related company permissions The exact role mapping is implemented in the shared security and application services.

Outbound Interfaces​

DEUSS Core Payment Service​

DEUSS Core Payment Service is the primary internal payment backend dependency. Payment Service calls it to:

  • Retrieve payments for a wallet
  • Retrieve a payment by deal ID
  • Retrieve a payment by transaction reference
  • Retrieve bond paydays
  • Retrieve payment status history DEUSS Core Payment Service remains responsible for blockchain-aware payment processing and payment lifecycle state.

Company Service​

Company Service is used for company-related authorization and payment context. The Payment Service depends on it to determine whether the current user has permission to access payments related to a buyer or seller company.

Payment Provider​

Payment Service communicates with the external Payment Service Provider (PSP) for payment operations. The integration supports:

  • Sending payment-related requests
  • Payment Provider authentication
  • Provider-specific callbacks
  • Provider IBAN updates
  • Configurable enablement of actual Provider API calls
  • Mock mode for local or test environments

Validation App​

The Validation App is used for AML processing. The workflow is:

  1. Payment Provider requests an AML check.
  2. Payment Service coordinates the AML request with the Validation App.
  3. Validation App sends the AML result back.
  4. Payment Service updates the local payment AML state.

PostgreSQL​

The service uses its own PostgreSQL database through JPA/Hibernate. Flyway manages schema migrations.

Kafka Integration​

Status: No direct Kafka producers or consumers were identified in the analyzed service source. Although the service depends on shared Kafka libraries, the payment workflow is implemented primarily through:

  • REST APIs
  • Scheduled or service-level processing
  • Internal HTTP clients
  • External Payment Provider callbacks Any event-driven processing is not explicitly verified in the available Payment Service source.

Payment Processing Model​

Payment Retrieval​

  1. A user requests payments for a wallet.
  2. Payment Service validates access to the wallet and related company.
  3. Payment Service calls DEUSS Core Payment Service.
  4. Returned payments are enriched with the locally stored marked_as_paid flag.
  5. The result is returned to the client.

Payment Instructions​

  1. A sender requests instructions using a payment reference.
  2. Payment Service loads the local payment record.
  3. It verifies that the Provider IBAN, price, and currency are available.
  4. It returns:
    • Payment Provider name
    • Payment Provider IBAN
    • Amount
    • Currency
    • Payment reference
    • Creation time

Payment Synchronization​

When a payment is not available locally, or needs to be refreshed:

  1. Payment Service requests the payment from DEUSS Core Payment Service.
  2. It maps the response into a local payment record.
  3. Receiver wallet references are stored locally.
  4. Existing records are updated; missing records are inserted.

Payment Provider Callback​

The Payment Provider can update the service with:

  • AML initiation requests
  • Provider IBAN information
  • Payment-provider-side payment status information The service validates the request and updates its local payment state.

AML Workflow​

The service coordinates AML checks for payments.

Supported States​

  • NEW ,REQUESTED ,OK ,DENIED ,EXPIRED

Workflow​

  1. Payment Provider calls the AML endpoint.
  2. Payment Service resolves the referenced payment.
  3. The AML process is delegated to the Validation App.
  4. Validation App returns the AML result.
  5. Payment Service stores the result against the payment. The exact AML decisioning logic is implemented through the Validation App integration. Payment Service acts primarily as the workflow coordinator and persistence layer.

Key Business Rules​

  1. Payment access is restricted based on the requesting user's relationship to the payment's buyer or seller company.
  2. Payment references are managed by the external Payment Service Provider (PSP).
  3. Payment Provider IBAN must be available before payment instructions can be returned.
  4. Payment price and currency must be available before payment instructions can be generated.
  5. Payment data is synchronized from DEUSS Core Payment Service.
  6. The local marked_as_paid flag is maintained independently from the payment state in DEUSS Core Payment Service.
  7. Payment Provider callbacks require Basic Authentication.
  8. AML results are accepted only for an existing payment reference.
  9. Payment Provider API calls can be disabled through configuration.
  10. DEUSS Core Payment Service remains the source for blockchain-aware payment lifecycle information.
  11. Bond payday information is retrieved from DEUSS Core Payment Service rather than calculated locally.
  12. A default Payment Provider name is used when payment instructions are generated.

Deployment​

Runtime Stack:

  • Kotlin
  • Micronaut
  • Java 25 OpenJDK runtime
  • Netty
  • PostgreSQL
  • Hibernate/JPA
  • Flyway
  • OpenAPI-generated internal clients
  • Argon2 password hashing for external authentication
  • Apollo GraphQL runtime dependency, where applicable through shared integrations Configuration:
  • Application name: payment-service
  • HTTP port: 8080
  • Database: payment_service_db
  • Kafka group ID configured as payment-service
  • Flyway migrations enabled
  • Client retries and circuit-breaker settings configured
  • Payment Provider API calls configurable
  • Mock clients available for selected external services Relevant Environment Variables:
  • DATABASE_URL
  • DATABASE_USER
  • DATABASE_PASSWORD
  • COMPANY_SERVICE_URL
  • CORE_PAYMENT_SERVICE_URL
  • VALIDATION_APP_URL
  • PAYMENT_PROVIDER_HOST
  • PAYMENT_PROVIDER_TOKEN
  • PAYMENT_PROVIDER_USERNAME
  • PAYMENT_PROVIDER_PASSWORD_HASH
  • PAYMENT_PROVIDER_ENABLE_API_CALLS
  • CLIENT_ATTEMPTS
  • CLIENT_DELAY
  • CLIENT_CIRCUIT_BREAKER_RESET
  • COMPANY_SERVICE_MOCK_ENABLED
  • CORE_PAYMENT_SERVICE_MOCK_ENABLED
  • VALIDATION_APP_MOCK_ENABLED
  • PAYMENT_PROVIDER_MOCK_ENABLED
  • CLIENT_MOCK_AUTH
  • INDEXER_URL
  • CHAIN_ENABLED Container:
  • Alpine-based image
  • OpenJDK 25
  • Runs under a non-root runtime user
  • Uses tini as the init process
  • Enables JVM container support

External Integrations​

DEUSS Core Payment Service​

Internal payment backend responsible for blockchain-aware payment processing.

Company Service​

Internal service used for company-related authorization and payment access checks.

Payment Provider​

External system responsible for receiving and distributing funds.

Validation App​

External or partner-facing service responsible for AML validation results.

PostgreSQL​

Owned database for the local payment and AML view.

Observability​

  • Structured logging through DeussLogger
  • Logging of Payment Provider callback processing
  • Configurable client retries and circuit-breaker reset
  • Validation and error logging for external callbacks
  • Flyway migration tracking
  • Standard Micronaut health and utility endpoints through the shared framework
  • Metrics integration: not verified in the analyzed source

Architectural Characteristics​

  • Payment Gateway Layer — Provides a Broker Platform-facing API over DEUSS Core Payment Service and the external Payment Service Provider (PSP).
  • Local Read Model — Stores payment-provider-specific data and local flags required by the Broker Platform application.
  • Delegated Blockchain Processing — Does not own the blockchain payment lifecycle; delegates it to DEUSS Core Payment Service.
  • Synchronous Integration Model — Relies mainly on REST calls and callbacks.
  • AML Coordination Layer — Connects Payment Provider, Validation App, and local payment records.
  • Client Resilience — Internal and external clients support configurable retries, delays, circuit-breaker reset, and mocks.
  • Multi-Provider Preparation — The schema and README indicate that multiple Payment Providers may be supported in the future, although the current implementation uses a default Provider name.

Relationships with Other Services​

  • DEUSS Core Payment Service
    • Provides authoritative payment and payday information
    • Handles blockchain-aware payment processing
    • Receives and exposes payment status history
  • Company Service
    • Supports payment visibility and company authorization checks
    • Provides company-related payment context
  • Payment Provider
    • Receives payment-related requests
    • Sends AML and payment instructions callbacks
    • Provides Provider IBAN information
  • Validation App
    • Performs AML checks
    • Sends AML results back to Payment Service
  • Indexer / Blockchain
    • Not queried directly by the primary Payment Service flow verified here
    • Blockchain-derived payment data is accessed through DEUSS Core Payment Service

Documentation Sources:

  • Source: whitelabel/payment-service/src/main/kotlin/
  • Controllers: whitelabel/payment-service/src/main/kotlin/cz/deuss/paymentservice/controller/
  • Services: whitelabel/payment-service/src/main/kotlin/cz/deuss/paymentservice/service/
  • Clients: whitelabel/payment-service/src/main/kotlin/cz/deuss/paymentservice/client/
  • Database models: whitelabel/payment-service/src/main/kotlin/cz/deuss/paymentservice/database/model/
  • Migrations: whitelabel/payment-service/src/main/resources/db/migration/
  • Public API: api-specifications/src/main/resources/whitelabel/payment-service/public/payment-public.openapi.yaml
  • Partner API: api-specifications/src/main/resources/whitelabel/payment-service/public/payment-partners.openapi.yaml
  • Configuration: whitelabel/payment-service/src/main/resources/application.yaml
  • Container: whitelabel/payment-service/Dockerfile
  • Build dependencies: whitelabel/payment-service/build.gradle.kts