Security & Compliance
Kulpay API implements multiple layers of security to protect financial data and ensure regulatory compliance.
Authentication & Authorization
License-Based System Authorization
Kulpay API uses a license key system to authorize the deployment itself. The license is validated at the middleware level on every incoming request — however, there is no per-request Authorization header. The system holds the license internally and validates it automatically.
| State | Description |
|---|---|
active | License is valid and the system serves requests |
expired | License has passed its expiration date |
invalid | License has been deactivated or revoked |
The License Interceptor middleware validates the stored license on every request. Background revalidation occurs periodically (every 30 seconds in development) to detect external revocations.
Technical Decision: The license model authorizes the deployment, not individual users. This was chosen because Kulpay API operates as middleware within the partner's infrastructure. Per-request user authentication is planned for future multi-tenant scenarios.
Data Protection
Encrypted Fields
Sensitive customer data is encrypted at rest:
| Field | Model | Encryption |
|---|---|---|
nationality_id | Customer | AES encryption |
tax_id | Customer | AES encryption |
nuib | Customer | AES encryption |
Device Fingerprinting
Device identifiers (IMEI) are hashed before storage, ensuring that raw hardware identifiers are never persisted.
Password Security
- PIN/password hashing uses bcrypt with appropriate cost factors
- Failed authentication attempts are tracked (3-attempt limit before account suspension)
KYC/AML Compliance
The KYC (Know Your Customer) process ensures regulatory compliance through:
Document Verification
- Supported documents: Passport, DIRE (national ID), BI (identity card)
- Document front and back images are captured and verified
- Optical Character Recognition (OCR) extracts document data
Biometric Verification
- Liveness detection via MiniAiLive prevents spoofing
- Face matching compares selfie against document photo
- Results are stored with the KYC record for audit trail
NUIB Verification
- Integration with the national NUIB API (Mozambique)
- Cross-references customer identity against government records
- Results stored for compliance records
KYC Status Workflow
Risk Assessment
- Customer segmentation:
personalorbusiness - Automated risk scoring during onboarding approval
- Regulatory list checking (sanctions, PEP lists)
Transport Security
| Layer | Protection |
|---|---|
| TLS | All gRPC and HTTP connections support TLS encryption |
| CORS | Configurable allowed origins, methods, and headers |
| HTTPS | HTTP to HTTPS upgrade recommended for production |
Audit Trail
- All KYC reviews are logged with reviewer ID and timestamps
- Transaction history maintains complete records
- KYC log messages provide a full audit trail of status changes and reviewer comments
- Device information is captured at login for security monitoring