Quick Start

When analyzing HumoPay services, use this context to understand:

• Payment processing flows
• Service interactions
• Banking terminology
• Architecture patterns
• Common pitfalls

This skill provides context only - it doesn't execute actions automatically.

HumoPay Platform Overview

HumoPay is an internal payment platform for banking operations.

Core purposes:

• Financial transaction processing
• External provider integrations
• Payment routing
• Unified API for agents and internal systems
• High-load, fault-tolerant processing

Transaction types:

• Client payments
• QR payments
• Merchant payments
• Interbank operations
• Wallet top-ups
• Loan repayments
• External bank operations
• B2B integrations

Architecture Components

Component	Purpose
xmlgate	External gateway for agents
processor	Central orchestration/payment engine
aggregators	Provider integrations
humopay_limits	Blacklist and limit service
FraudMachine	Antifraud service
interchange	Reconciliation and registry processing
FalconApi	Admin panel backend
FalconFront	Admin panel frontend
Keycloak	Admin authentication
Redis	Cache and rate limiting
PostgreSQL	Transactional storage

Common Payment Flow

TEXT
Agent → xmlgate → processor → aggregator → provider → response back

Typical flow includes:

• Signature validation
• Endpoint validation
• Transaction persistence
• Blacklist/antifraud checks
• Balance updates
• Retries
• Postcheck
• Reconciliation

Most operations are asynchronous.

XMLGate Service

Purpose: Main external gateway

Responsibilities:

• Accept agent requests
• Authentication
• Signature validation
• Rate limiting
• Route to processor
• Return XML responses

Technical features:

• HTTP GET API
• XML-based protocol
• SHA256 signatures
• Idempotency via trnx_id
• Async processing
• Redis caching

Processor Service

Purpose: Central payment engine

Responsibilities:

• Payment lifecycle management
• Orchestration processing
• Transaction management
• Balance updates
• Blacklist/limit checks
• Aggregator communication
• Retry processing

Common payment statuses:

• 102 - Processing
• 200 - Success
• 202 - Accepted
• 206 - Requires postcheck
• 400 - Error
• 408 - Timeout

Common Database Tables

Table	Purpose
tpayments	Payment records
tpaymentlog	Status history
tagents	Agent configuration
tendpoints	Endpoint settings
tservices	Available services
tgateways	Routing configuration
tacctlog	Accounting logs

Infrastructure Context

Production environment:

• Services run via systemd
• Manual deployment by DevOps
• Direct server execution
• Manual updates

Test environment:

• Docker Swarm
• CI/CD pipelines
• Container-based

Don't assume presence of:

• Kubernetes
• Helm
• ArgoCD
• Production CI/CD
• Automated rollbacks
• Monitoring URLs
• Alert channels

Unless explicitly confirmed in code/configuration.

Best Practices

When analyzing HumoPay services:

1. Check actual code - Don't assume architecture patterns
2. Look for XML protocols - Most APIs are XML-based
3. Expect async processing - Most payments are asynchronous
4. Check retry mechanisms - Critical for fault tolerance
5. Verify database tables - Payment entities are complex
6. Review aggregator integrations - Each provider is unique

When generating documentation:

1. Focus on payment flows - Show transaction lifecycle
2. Include status codes - Payment statuses are critical
3. Document retry logic - Essential for operations
4. Explain idempotency - Duplicate protection is key
5. Show error handling - Financial systems need robust error handling

Common Pitfalls

Don't assume:

• Clean Architecture patterns
• Synchronous processing
• REST APIs (mostly XML)
• Standard directory structures
• Modern deployment practices in production
• Monitoring infrastructure without confirmation

Do verify:

• Actual transport protocols
• Database schemas
• Configuration files
• Integration patterns
• Deployment methods
• Error handling strategies

Financial transaction considerations:

• Idempotency is critical
• Audit trails are mandatory
• Retry logic affects consistency
• Status transitions must be tracked
• Reconciliation is essential

When to Use This Context

Apply this context when:

• Analyzing HumoPay service code
• Generating technical documentation
• Reviewing transaction flows
• Writing ADRs
• Describing business processes
• Analyzing integrations
• Creating workflow documents
• Describing payment lifecycle
• Performing code reviews

This context supplements code analysis - always verify assumptions against actual implementation.