Data Models

This page documents the core data models used throughout the Kulpay API system.

Entity Relationship Diagram

Customer

The Customer is the central entity in the system. Each customer has an embedded Account that links to the BLNK core banking engine.

Field	Type	Description
customer_id	string	Unique ID with cus_ prefix
first_name	string	Customer's first name
last_name	string	Customer's last name
other_names	string	Additional names (optional)
email	string	Unique email address
phone_number	string	Unique phone number (E.164 format)
account	Account	Embedded BLNK account link (see below)
address	Address	Physical address (street, city, country, postal_code)
nationality_id	string	National ID or passport number (encrypted)
tax_id	string	Tax identification number (encrypted)
nuib	string	National Unified ID Number (encrypted)
customer_segment	enum	personal or business
kyc_status	enum	initiated, under_review, pending, verified, rejected
status	enum	active, suspended, closed
sex	string	Customer's sex
date_of_birth	timestamp	Date of birth
nationality	string	Nationality
profile_picture	UploadedFile	Optional profile image
qrcode_id	string	Generated upon KYC verification
business_name	string	Business name (for business segment)

Account

The Account is embedded within the Customer model and serves as the bridge between Kulpay API and the BLNK core banking engine.

Field	Type	Description
identity_id	string	BLNK Identity ID — links the customer to their BLNK identity
balance_id	string	BLNK Balance ID — links to the customer's wallet balance in BLNK

Technical Decision: Rather than maintaining balances directly, Kulpay API delegates all balance and ledger operations to BLNK. The Account model stores only the references needed to query BLNK. This separation ensures that Kulpay API handles customer lifecycle and business logic while BLNK manages the financial ledger with double-entry accounting guarantees.

PhoneSession

Manages OTP verification during customer onboarding and sensitive operations.

Field	Type	Description
phone_number	string	Phone number being verified (indexed)
otp	string	6-digit one-time password
expires_at	timestamp	OTP expiration time (indexed)
verified	boolean	Whether the OTP was successfully verified
created_at	timestamp	When the session was created
verified_at	timestamp	When verification succeeded
attempt_count	integer	Number of verification attempts (max 3 before lockout)

Bill

The Bill model is a comprehensive invoicing structure supporting both simple and complex billing scenarios.

Field	Type	Description
id	string	Unique bill identifier
account_id	string	Customer account ID
type	enum	invoice or recharge
description	string	Bill description
amount	Amount	Bill amount (value + currency)
status	string	PENDING, COMPLETED, CANCELLED, FAILED
payer	Payer	Payer details
biller	Biller	Biller/issuer details
invoice_metadata	InvoiceMetadata	Invoice-specific metadata
financial_details	FinancialDetails	Line items, tax, discounts
payment_reconciliation	PaymentAndReconciliation	Payment and reconciliation tracking
integration_routing	IntegrationAndRouting	ERP and routing configuration
compliance_audit	ComplianceAndAudit	Audit trail with timestamps
collection_method_details	array	Collection methods (NIB, entity number, etc.)
third_party_reference	string	External reference ID

Biller

Field	Type	Description
account_id	string	Biller's account ID
business_name	string	Business name
logo	UploadedFile	Business logo
contact	Contact	Phone and email
issuer_nuit	string	Tax ID (NUIT) of the issuer
billing_address	Address	Biller address

InvoiceMetadata

Field	Type	Description
invoice_number	string	Unique invoice number
issue_date	string	When the invoice was issued
due_date	string	Payment due date
invoice_type	string	Type of invoice
source_channel	string	Channel the invoice originated from
reference_number	string	External reference
payment_link	string	Link for online payment

FinancialDetails

Field	Type	Description
line_items	string	Description of line items
products_info	ProductsInformation	Product details
tax_info	TaxInformation	Tax breakdown
discount	number	Discount amount
total_amount	Amount	Total after tax and discounts
fx_rate	string	Foreign exchange rate (if applicable)

ComplianceAndAudit

Field	Type	Description
payer_nuit	string	Payer's tax ID (NUIT)
issuer_nuit	string	Issuer's tax ID (NUIT)
invoice_validity	string	Validity period
attached_contract	string	Contract reference
user_issuer	string	User who issued the bill
issued_at	string	Timestamp of issuance
viewed_at	string	When the bill was viewed
paid_at	string	When payment was received
reconciled_at	string	When reconciliation occurred

Instruction

An Instruction represents a financial operation request that is processed by a payment adapter. It is the core transactional unit in Kulpay API.

Field	Type	Description
id	string	Unique instruction ID
customer_id	string	Customer who initiated the instruction
type	enum	transfer, deposit, pay_in, pay_out, pay_bill, check_balance, get_authorization, validata
status	enum	pending, processing, succeeded, failed
payload	Payload	Transaction details (embedded)
adapter_impl	string	Which payment adapter processes this instruction
contacts	Participant[]	Participants involved (sender, receiver)
retries	integer	Number of processing retries
processed_at	timestamp	When processing completed
notify_customer	boolean	Whether to send SMS notification

Payload

Field	Type	Description
transactions	Transaction[]	List of transactions to execute
receive_transaction	string	Receiving transaction reference
payment_method_type	string	Type of payment method used
instruction_value_date	timestamp	Scheduled execution date

Transaction (within Payload)

Field	Type	Description
id	string	Transaction ID
amount	number	Transaction amount
currency	string	ISO currency code (e.g., MZN)
from	string	Source account/reference
to	string	Destination account/reference
description	string	Transaction description
allow_overdraft	boolean	Whether overdraft is permitted
scheduled_for	timestamp	Scheduled execution time

Participant

Field	Type	Description
id	string	Participant ID
name	string	Full name
email	string	Email address
phone	string	Phone number
address	string	Address
role	enum	sender or receiver
picture	UploadedFile	Profile picture

LicenseKey

Controls system-level authorization for the Kulpay API deployment.

Field	Type	Description
id	string	Unique license ID
key	string	License key value (indexed)
status	enum	active, expired, invalid
issued_to	string	Partner/organization the license was issued to
issuer	string	License issuer (e.g., kulpay)
issued_at	timestamp	When the license was issued
expires_at	timestamp	When the license expires

Common Types

UploadedFile

Represents a file stored in the Minio-backed file server.

Field	Type	Description
file_id	string	Unique file identifier
file_bucket	string	Minio storage bucket name
file_link	string	Download link (base64)

Money / Amount

Field	Type	Description
amount	string	Decimal amount
currency	string	ISO 4217 currency code (e.g., MZN)

Error

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable description
request_id	string	Request tracking ID (req_ prefix)
metadata	map	Additional error context