External Integrations
The Kulpay platform integrates with several external services to provide identity verification, payment processing, file storage, communication, and authentication capabilities.
Integration Architecture
Core Banking: BLNK
BLNK is the core banking engine powering the Kulpay digital wallet. It is not simply a payment adapter — it is the central ledger that manages all wallet balances, identities, and transactions with double-entry accounting guarantees.
| Capability | Description |
|---|---|
| Identity Management | Each customer is linked to a BLNK identity via Account.identity_id |
| Balance Management | Wallet balances are maintained in BLNK via Account.balance_id |
| Double-Entry Ledger | All transactions are recorded with debit/credit entries |
| Transfer Processing | Wallet-to-wallet transfers, deposits, and withdrawals |
| Balance Queries | Real-time balance lookups |
| Transaction History | Full ledger history for each identity |
Technical Decision: BLNK was chosen as the core banking engine rather than building an in-house ledger. This provides battle-tested double-entry accounting, eliminates the risk of balance inconsistencies, and allows Kulpay API to focus on business logic while BLNK handles financial integrity. The
Accountmodel in Kulpay API stores onlyidentity_idandbalance_idreferences — all balance state lives in BLNK.
Integration Flow
Identity Verification
LiveAIEngine (Biometrics)
LiveAIEngine provides biometric verification services for the KYC process.
| Capability | Description |
|---|---|
| Liveness Detection | Verifies that the selfie is from a live person, not a photo or video |
| Face Matching | Compares the selfie against the ID document photo |
| Document OCR | Extracts text data from identity documents (name, DOB, ID number, address) |
Integration Flow:
NUIB API
The NUIB (National Unified Identification Bureau) API provides government-level identity verification for Mozambican customers.
| Capability | Description |
|---|---|
| Identity Lookup | Verifies customer identity against national records |
| Data Cross-reference | Confirms name, DOB, and ID number match government data |
| Compliance Check | Required for regulatory compliance in Mozambique |
Communication
SMS Provider
Used for OTP delivery during customer onboarding and transaction authorization.
| Use Case | Description |
|---|---|
| Phone Verification | Sends 6-digit OTP during account creation |
| Transaction Authorization | Sends authorization codes for financial operations |
| KYC Notifications | Notifies customers of KYC status changes |
| Account Notifications | Account recharge and transaction confirmations |
Storage: Minio
Kulpay API uses a self-hosted Minio instance for all file storage needs. Minio provides an S3-compatible object storage API.
| Capability | Description |
|---|---|
| Document Storage | ID document images (front/back) |
| Selfie Storage | Customer selfie/liveness images |
| Profile Pictures | Customer profile photos |
| Business Logos | Partner and bill business logos |
| File Retrieval | Base64-encoded download via file links |
Files are organized into buckets and referenced via UploadedFile objects containing file_id, file_bucket, and file_link.
Technical Decision: Minio was chosen over cloud storage providers (S3, GCS) to maintain full data sovereignty. Since Kulpay API processes sensitive identity documents and financial data, self-hosting the file server ensures that all data remains within the partner's infrastructure without external dependencies.
QR Code Service
A standalone microservice developed in-house for QR code generation, scan handling, and customer identification. When a QR code is scanned, the generated link points to this service first — it handles the scan event, performs tracking, and then routes the request to the Kulpay API for resolution.
| Capability | Description |
|---|---|
| QR Generation | Creates unique QR codes for customers upon KYC verification |
| Scan Handling | QR code links resolve to this service, which controls the scan flow before reaching Kulpay API |
| Scan Tracking | Records when and how many times a QR code is scanned |
| Customer Lookup | Resolves a QR code to a customer identity for transfers |
| Agent Integration | Agents scan customer QR codes for Cash-In and Cash-Out operations |
| Merchant Payments | Informal merchants receive QR Code stickers that customers scan to pay |
Each customer's qrcode_id field links to their QR code in this service. QR codes serve as a convenient alternative to account numbers for in-person transactions.
Technical Decision: The QR code service was developed as a standalone microservice rather than using a third-party solution to enable deep integration with the customer lifecycle (auto-generation on KYC approval), to control the scan-to-resolution flow, and to add scan tracking analytics that off-the-shelf QR solutions don't provide.
Payment Adapters
Kulpay API uses an adapter pattern to support multiple payment providers through a unified interface. The Instruction Engine routes each instruction to the appropriate adapter based on the payment method type.
Adapter Architecture
Kulpay Adapter (BLNK)
Routes wallet operations to the BLNK core banking engine.
| Operation | Description |
|---|---|
| Balance Query | Check wallet balance |
| Deposit | Add funds to wallet |
| Transfer | Send funds to another wallet |
| Withdrawal | Remove funds from wallet |
| History | Retrieve transaction history |
Card Simo Adapter
Handles card-based payment processing through the SIMORede platform.
| Operation | Description |
|---|---|
| Validation | Validate card details |
| Authorization | Get transaction authorization |
| Pay In | Process card payment |
| Pay Out | Process card payout |
Bank Adapter
Traditional banking operations adapter (extensible for multiple bank integrations).
| Operation | Description |
|---|---|
| Transfer | Bank transfer via NIB |
| Balance | Account balance query |
Technical Decision: The adapter pattern was chosen to decouple transaction processing from specific payment providers. Adding a new payment provider requires implementing a single adapter interface without modifying the instruction engine or any service logic. This makes the system extensible for new banking partners.
Authentication: Keycloak
The Collection API uses Keycloak as its OIDC-compliant identity provider for merchant authentication and authorization via the Hakela dashboard.
| Capability | Description |
|---|---|
| User Authentication | Merchant login via OpenID Connect |
| Token Issuance | JWT access and refresh tokens |
| User Management | Merchant user registration, password recovery |
| Role-Based Access | Fine-grained permissions for merchant portal operations |
Integration Points
- Token Validation — JWTs are validated against Keycloak's JWKS endpoint
- User Info — User identity extracted from token claims
- Session Management — End session endpoint for logout flows
- Token Introspection — Active token verification for server-side flows
- Token Revocation — Invalidate tokens on logout or security events
Identity providers are managed through the Identity Provider Service.
Webhook Integrations
The Collection API supports event-driven integrations via webhooks for the invoice lifecycle:
| Event | Direction | Description |
|---|---|---|
bill-created | Biller → API | New invoice ingested |
bill-delivered | API → Biller | Invoice delivered to payer |
bill-opened | Kulpay App → API | Customer viewed invoice |
bill-paid | Biller/Bank → API | External payment notification |
customer-paid | Kulpay App → API | In-app payment confirmation |
kulpay | API → Kulpay App | Push notification to customer |
See Webhooks & Events for endpoint details and payloads.