Billing & Payments

Condo’s billing and payment system connects external accounting systems to residents, delivering monthly receipts and enabling online payment collection through acquiring integrations.

​

Billing Receipts

A BillingReceipt is a monthly invoice document for a specific billing account and period. Receipts are imported from an external accounting system via a billing integration connector.

​

Key Fields

​

Billing Accounts

A BillingAccount represents a resident’s utility account number as it exists in the external billing system.

​

Billing Integrations

A BillingIntegration defines a connector that can pull receipt data from a specific type of billing system (e.g., 1C, municipal billing platforms). Each integration has:

• A name and logo for display in the management UI
• A dataFormat describing the data schema it provides
• A currencyCode for all receipts from this integration
• appUrl / instructionExtraLink for the mini-app or setup guide

To activate an integration for an organization, a BillingIntegrationOrganizationContext is created and moves through the setup flow to the finished status (CONTEXT_FINISHED_STATUS). Only finished contexts allow receipts to be imported and payments to be processed.

​

Receipt Registration

Receipts are registered in bulk via RegisterBillingReceiptsService. This service:

1. Validates receipt data against the integration’s data format schema
2. Creates or updates BillingAccount and BillingProperty records
3. Upserts BillingReceipt records (identified by importId)
4. Triggers BILLING_RECEIPT_AVAILABLE push notifications to affected residents

PDF receipt files can be attached via RegisterBillingReceiptFileService, resulting in a BILLING_RECEIPT_FILE_ADDED notification.

​

Acquiring & Online Payments

Payments flow through an acquiring integration — a payment gateway connector registered as an AcquiringIntegration.

​

Payment Flow

​

Payment Statuses

Payment status constants are defined in domains/acquiring/constants/payment.js:

​

Fee Structure

Condo supports a detailed fee model on each Payment:

• amount — Amount allocated to the billing receipt
• explicitFee — Service fee paid by the resident on top of the bill amount (for non-HCS services)
• explicitServiceCharge — Internal service charge for HCS payments
• implicitFee — Fee deducted from the recipient’s payout
• serviceFee — Condo’s net platform fee after splitting

​

Recurrent Payments

Residents can enable auto-pay by creating a RecurrentPaymentContext, which stores their payment authorization (card token) and payment schedule. Each month, Condo’s background worker creates RecurrentPayment snapshots and processes them automatically. Residents receive advance notice notifications (RECURRENT_PAYMENT_TOMORROW_PAYMENT_MESSAGE) and outcome notifications on success or failure.

​

QR Code Payments

Condo supports scanning payment QR codes from paper receipts via ValidateQRCodeService. The service extracts the billing account and amount, allowing the resident to pay directly from the app without manual entry. Rate limiting applies: up to 10 QR validations per hour per client.

​

Notifications