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 the Core API operates as middleware within the partner's infrastructure.

Collection API: API Key + OIDC Authentication

The Collection API extends the security model with per-request authentication via OIDC (OpenID Connect) identity providers. Each request must include a Bearer token in the Authorization header.

The Collection API validates through two layers:

1. System License — Same license interceptor as the Core API
2. Bearer Token — JWT validated against the OIDC provider's JWKS endpoint

The Collection API uses Keycloak as its OIDC identity provider. See Collection API Authentication for details.

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 LiveAIEngine 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: personal or business
• 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
• Collection API identity provider operations track created_by, updated_by, created_ip, and updated_ip
• Invoice compliance fields include payer_nuit, issuer_nuit, and full timestamp history (issued_at, viewed_at, paid_at, reconciled_at)