This document describes the entities, relationships, and data flows of the InsureMO BCP (Billing/Collection/Payment) module for General Insurance.

Entity Relationship Diagram

BcpBizTransaction ----> BcpFee --------------------------> GLIntegrationVoucherDetail
   (root)             (fee breakdown)                     (via GLMappingRule - Data Table)
   |
   +----> BcpArap <-----------------------------------------------+
   |      (AR/AP)                                                |
   |                                                             |
   |      +-----------------> BcpCollection -----> BcpCollectionDetail ----> BcpSuspense
   |      |                     (money in)        (detail)              (parked funds)
   |      |                                                                   |
   |      +--------------- BcpOffset <--------------------------------------------+
   |                     (AR/AP netting)                                         |
   |                                                                             |
   +----> BcpPayment ----> BcpPaymentDetail ----> BcpArap                       |
        (money out)        (detail)           (direct clear, NO Offset)           |
                                                                                 |
                                                                         (Suspense used in Offset)

Core Entities

BcpBizTransaction — Root Business Transaction

The root object for every financial activity in BCP. Immutable once created.

API: loadBizTransaction, loadBizTransactionsByRefTransId, queryEsData

BcpFee — Fee Component

Raw data source for GL generation. Contains detailed fee breakdowns (Net Premium, Tax, Commission). The original Fee created during billing is immutable once sent, but new Fee records are generated during each subsequent transaction (Collection, Payment, Offset, Reverse) to record fee movements for GL.

One BizTransaction can produce multiple Fee records. Each fee may:

• Enter BcpArap — trigger receivable/payable creation
• Enter SalesCommission — create commission records in orchestration layer
• Send to GL — map to General Ledger via GLMappingRule - Data Table

API: syncDataToBCP, getFeeList, syncAdditionalFeeToBCP

BcpArap — Accounts Receivable / Payable

Tracks BCP transaction status (Outstanding, Paid, Cancelled) and balance (remaining amount to collect/pay).

Key Rule: One business data transmission with multiple fee components generates one AR or one AP per installment.

BcpCollection — Collection Record

Money received from customers (premium payments, endorsements, prepayments).

CollectionDetail sub-records:

Timestamp Fields

BcpCollection carries three categories of timestamps. Each business-event timestamp has a paired System variant that records the actual system-clock time at processing (useful for audit when the business time was back-dated or forward-dated).

Business-event timestamps — when the business event nominally occurred (the *Time fields; set only if not already provided, so they may be back-dated by the caller):

System timestamps — the real system clock at processing; unconditionally overwritten and not editable by the caller:

Audit timestamps — inherited from the base domain model (set via @PrePersist / @PreUpdate), not Collection-specific:

API: collectionApplication, confirmCollection, policyCollectionAndOffset, producerCollect

BcpSuspense — Suspense Record

Temporarily parked funds awaiting allocation or reconciliation.

SuspenseDetail sub-records:

BcpOffset — Offset / Settlement Record

AR/AP netting engine. Matches AR and AP entries to reduce balances to zero. Does NOT involve Payment.

OffsetDetail sub-records — links Offset to source records:

API: arapOffset, toleranceOffset, reverseOffset

BcpPayment — Payment (Disbursement) Record

Money going out: claim payouts, premium refunds (endorsement/cancellation). Does NOT go through Offset. Directly clears BcpArap balance.

PaymentDetail sub-records:

Important: PaymentDetail.RefType is always 3 (ARAP), unlike OffsetDetail which uses both RefType 2 (Suspense) and RefType 3 (ARAP).

PaymentStatus lifecycle:

[Created] → Status 2 (Approved) → Status 3 (Paid) → Status 5 (Reversed)
                           │
                           └──► singlePayment API
                                sets ArapStatus=2 (Settled)
                                sets Arap.Balance=0
                                updates SalesCommission.CommissionStatus=2

API: approvePaymentWithEs, approvePaymentByArapIds, approvePaymentAdvanced, approveStatementPayment, singlePayment, massivePayment, receiptRefund, reversePayment

BcpPrepayOrder — Prepayment Order

Prepayment orders created when IsPrepay="Y" (Cash Before Cover). Not tracked as ARAP or Fee — settled via Balance and OrderStatus fields.

BcpReverse — Reversal Record

Records reversal operations for Collection, Payment, and Offset transactions.

Currency & Exchange Rate

Every BCP financial record (BcpBizTransaction, BcpFee, BcpArap, BcpCollection, BcpPayment, BcpOffset, and their detail lines) carries four currency codes and a set of direct exchange-rate (ER) fields to support cross-currency billing, booking, and collection.

Currency Codes

Direct Exchange-Rate Fields

Each Direct*Er field converts from CurrencyCode to a target currency:

Direction Convention

Rates are fetched at runtime from the Currency service (CurrencySdkClient.currencyExchangeApi().getExchangeRate(currency=<CurrencyCode>), returning sourceCurrencyCode plus a Map<targetCurrency, rate>). Daily rates are maintained under Global Configuration > Exchange Rate.

Examples

Worked example: Amount = 100 USD, DirectEr = 7.1 → local amount = 100 × 7.1 = 710 CNY.

Offset: Additional Currency Dimension

BcpOffset and BcpOffsetDetail carry OffsetCurrencyCode and OffsetDirectEr in addition to the standard currency/ER fields, because the AR/AP being offset may have been recorded in a different currency than the current offset operation.

Per the direction convention (source = CurrencyCode):

OffsetCurrencyCode (original) amount = CurrencyCode (this operation) amount × OffsetDirectEr

Example: OffsetCurrencyCode = CNY (AR/AP original), CurrencyCode = USD (this offset operation) → OffsetDirectEr = 7.1 (1 USD = 7.1 CNY; a 100 USD operation = 710 CNY in the AR/AP’s original currency).

GL Accounting Entities

GLIntegrationVoucherDetail — GL Voucher Detail

Accounting representation of BCP Fee events. Created from BcpFee via GLIntegrationMappingRule double-entry transformation.

Dynamic segments (defined in Data Dictionary BCP_GL_INT_DD):

• Custom fields: GL_Account_Code, Department_ID, BranchCode, etc.
• Filled by Groovy expressions from GLMappingRule

API: queryGLByConditionEx

Physical Tables:

Both tables share the same DD model (GLIntegrationVoucherDetail). The distinction is whether queryVoucherDetailsOrderByIdForPostGL has been called — once called and completed, records are moved to the _his table.

GLIntegrationMappingRule — GL Mapping Rule Configuration

DataTable configuration (dataTableName: GLIntegrationMappingRule) that defines how BcpFee transforms into GL Voucher Details (single-entry BCP Fee → double-entry GL).

Condition Types:

• FeeType Mapping — Match specific BCP fee type (e.g., 100501 for Direct Premium)
• FilterExpression — Groovy script for complex logic

FilterExpression Context Objects:

GLIntegrationPostBatch — GL Post Batch

Groups vouchers for a specific accounting period before transmitting to the external GL system.

Posting Workflow:

1. createGLPostBatchRecord — Create batch with due date
2. Transmit to external GL system
3. completePostBatch — Mark vouchers as “Completed”

Data Flows

Billing Flow

BizTransaction -> BcpFee
                   |
                   +-> (EnterBcpArap) -> BcpArap
                   +-> (SendToGL)     -> GLIntegrationVoucherDetail
                                           via GLMappingRule

Collection Flow (Money In)

BcpCollection -> BcpCollectionDetail -> BcpSuspense
                                         |
                                         v
                               BcpOffset (RefType=2 -> Suspense)
                                         |
                                         v
                               BcpOffset (RefType=3 -> ARAP)
                                         |
                                         v
                                  BcpArap.Balance = 0

Payment Flow (Money Out) — No Offset Involved

BcpPayment (Status=2, Approved)
        |
        v singlePayment API
BcpPayment (Status=3, Paid)
        |
        +-> BcpPaymentDetail (RefType=3) -> BcpArap
        |                                    |
        |                               ArapStatus = 2 (Settled)
        |                               Arap.Balance = 0
        |
        +-> SalesCommission.CommissionStatus = 2

Receipt Refund Flow (Suspense -> Payment)

BcpSuspense (balance > 0)
        |
        v receiptRefund API
BcpPayment (Status=2)
        |
        +-> BcpPaymentDetail (RefType=2) -> BcpSuspense
                                              |
                                         Suspense.Balance = 0

GL Accounting Flow

BcpFee + GLIntegrationMappingRule
         |
         +-> GLIntegrationVoucherDetail (row 1: Debit)
         +-> GLIntegrationVoucherDetail (row 2: Credit)
                   |
                   v
         GLIntegrationPostBatch -> External GL System

RefType Reference

RefType values are context-dependent — the same RefType number means different things in different entities.

Entity ID Signing

Some APIs accept signed entity IDs (numeric,hash format). Use sign.py to generate signed values before calling those APIs.

DB Table Reference

Billing Related:

Transaction Related:

GL Integration Related: