External Integrations
Kulpay API integrates with several external services to provide identity verification, payment processing, file storage, and communication 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
MiniAiLive (Biometrics)
MiniAiLive 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
An in-house developed QR code management service used for customer identification and fund transfers.
| Capability | Description |
|---|---|
| QR Generation | Creates unique QR codes for customers upon KYC verification |
| 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 deposits and withdrawals |
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 in-house rather than using a third-party solution to enable deep integration with the customer lifecycle (auto-generation on KYC approval) 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.