Integrations

QuickBooks Chart of Accounts Setup Guide

This guide explains how to set up accounts in QuickBooks Online for integration with the Hiana Loans accounting module. The system posts journal entries to QuickBooks using internal account type codes — each must be mapped to a QuickBooks account.

Important: The system only posts journal entries to QuickBooks. It does not create accounts, bills, invoices, or customers via the API. You must create the accounts manually in QuickBooks first, then map them in Hiana Loans.

How It Works
Accounts Used by the System
QuickBooks Setup Steps
Recommended QuickBooks Account Types
Account Mapping
Journal Entry Reference
Minimum Viable Setup
Per-Product and Per-Jurisdiction Overrides
Posting Configuration
Troubleshooting
Quick Setup Checklist

How It Works

The Hiana Loans accounting module uses a double-entry journal entry system. When loan events occur (disbursement, payment, interest accrual, fee assessment, etc.), the system:

Generates a journal entry with debit and credit lines
Resolves internal account codes to your QuickBooks account codes via the account mapping table
Posts the entry to QuickBooks via the QuickBooks Online API (POST /v3/company/:id/journalentry)

Each internal account type (e.g., LOANS_RECEIVABLE, INTEREST_INCOME) must be mapped to a specific QuickBooks account. If a mapping is missing, the journal entry is rejected — the system will not post with unresolved account codes.

The integration uses three QuickBooks API operations only:

Operation	Purpose
`POST /journalentry`	Create journal entries
`GET /query` (Account)	Query account balances for reconciliation
`GET /companyinfo`	Test connection / verify credentials

No other QuickBooks API operations are needed.

Accounts Used by the System

These are the internal account codes that the journal entry builder actually references. Each one must have a mapping to a QuickBooks account.

Core Accounts (Required — 7 accounts)

#	Internal Code	Account Category	Purpose	Used By Events
1	`CASH`	Asset	Cash/bank for disbursements and repayments	Disbursement, Payment, Collateral Liquidation
2	`LOANS_RECEIVABLE`	Asset	Outstanding loan principal	Disbursement, Payment, Write-off, Guarantee Claim, Collateral Liquidation
3	`INTEREST_RECEIVABLE`	Asset	Interest accrued but not yet collected	Interest Accrual, Payment
4	`FEES_RECEIVABLE`	Asset	Fees assessed but not yet collected	Fee Assessment, Payment
5	`INTEREST_INCOME`	Income	Interest revenue recognized	Interest Accrual
6	`FEE_INCOME`	Income	Fee revenue (service fees)	Fee Assessment
7	`PENALTIES_RECEIVABLE`	Asset	Penalties assessed but not yet collected	Penalty Assessment, Payment

Extended Accounts (Required for full lifecycle — 4 accounts)

#	Internal Code	Account Category	Purpose	Used By Events
8	`PENALTY_INCOME`	Income	Penalty revenue recognized	Penalty Assessment
9	`LOAN_LOSS_PROVISION`	Contra-Asset	Allowance for expected credit losses (IFRS 9)	Loan Write-off
10	`GUARANTEE_RECEIVABLE`	Asset	Amount recoverable from guarantor after claim	Guarantee Claim
11	`DEFERRED_INTEGRAL_FEES`	Contra-Asset	Loan fees integral to EIR, amortised over loan life	Fee Assessment (optional, only if fee policy = integral EIR)

Collateral & Guarantee Accounts (Required for collateral liquidation — 4 accounts)

#	Internal Code	Account Category	Purpose	Used By Events
12	`GUARANTEE_LIABILITY`	Liability	Cash collateral held as guarantee liability	Guarantee Deposit
13	`REPOSSESSED_ASSETS`	Asset	Repossessed assets under lender control	Collateral Repossession
14	`COLLATERAL_RECOVERY`	Income	Gain/loss on collateral sale vs. outstanding balance	Collateral Repossession
15	`SURPLUS_PROCEEDS_PAYABLE`	Liability	Collateral sale surplus owed to borrower	Collateral Repossession, Surplus Payment

Tax Accounts (Required for tax provisioning — 4 accounts)

#	Internal Code	Account Category	Purpose	Used By Events
16	`INCOME_TAX_EXPENSE`	Expense	Current and deferred income tax expense	Tax Provisioning
17	`TAX_PAYABLE`	Liability	Current tax owed to revenue authorities	Tax Provisioning
18	`DEFERRED_TAX_ASSET`	Asset	Deferred tax asset (future deductible temporary differences)	Tax Provisioning
19	`DEFERRED_TAX_LIABILITY`	Liability	Deferred tax liability (future taxable temporary differences)	Tax Provisioning

Reserved Accounts (Seeded but not yet used by the builder)

These accounts exist in the system's chart of accounts for future use. You do not need to create them in QuickBooks until the corresponding features are activated.

Internal Code	Category	Intended Purpose
`IMPAIRMENT_LOSS_EXPENSE`	Expense	ECL provision expense when allowance is measured (future)
`IMPAIRMENT_RECOVERY`	Income	Recovery of previously written-off amounts (future)
`DIRECT_LOAN_ORIGINATION_COSTS`	Asset	Origination costs included in EIR calculation (future)

QuickBooks Setup Steps

Step 1: Create Accounts in QuickBooks

Log into QuickBooks Online
Go to Settings (gear icon) → Chart of Accounts (or search "Chart of Accounts" in the search bar)
Click New
For each account in the tables above:
- Select the Account Type (e.g., Bank, Other Current Asset, Income, Expense)
- Select the Detail Type (optional but recommended for reporting)
- Enter the Account Name (use a human-readable name, not the internal code)
- Leave the opening balance blank (the system will populate via journal entries)
- Click Save and Close
Repeat for each account

Important: Do not use the internal code (e.g., FEES_RECEIVABLE) as the QuickBooks account name. Use a readable name like "Fees Receivable". The internal code is mapped separately in Hiana Loans.

Step 2: Note QuickBooks Account IDs

When you create an account in QuickBooks, it assigns a numeric Account ID (e.g., 93). You can find this by:

Querying the account via the QuickBooks API, or
Looking at the account in the Chart of Accounts

You will need the QuickBooks Account ID (not the name) when creating the mapping in Hiana Loans. The mapping links your stable internal code to the QuickBooks account ID, so if someone renames the account in QuickBooks, the mapping still works.

Step 3: Enable QuickBooks Provider in Hiana Loans

Log into the Hiana Loans Admin Portal
Go to Accounting → External Providers
Find the QuickBooks provider
Click Configure Credentials and enter:
- Client ID
- Client Secret
- Refresh Token
- Company ID
Click Activate to enable the provider

Step 4: Create Account Mappings

Go to Accounting → Account Mappings
For each internal account type, map it to the corresponding QuickBooks account:
- Select the Internal Account Type (e.g., LOANS_RECEIVABLE)
- Enter the QuickBooks Account ID (the numeric ID from Step 2)
- Enter the QuickBooks Account Name (for display/reference)
- Click Save
Repeat for all accounts

Recommended QuickBooks Account Types

When creating accounts in QuickBooks, use these account types and detail types:

#	QB Account Type	Suggested Detail Type	Account Name	Internal Code
1	Bank	Bank	Operating Bank Account	`CASH`
2	Other Current Asset	Other Current Assets	Loans Receivable	`LOANS_RECEIVABLE`
3	Other Current Asset	Other Current Assets	Interest Receivable	`INTEREST_RECEIVABLE`
4	Other Current Asset	Other Current Assets	Fees Receivable	`FEES_RECEIVABLE`
5	Other Current Asset	Other Current Assets	Penalties Receivable	`PENALTIES_RECEIVABLE`
6	Income	Service/Fee Income	Interest Income	`INTEREST_INCOME`
7	Income	Service/Fee Income	Fee Income	`FEE_INCOME`
8	Income	Other Primary Income	Penalty Income	`PENALTY_INCOME`
9	Other Current Asset	Other Current Assets	Allowance for Expected Credit Losses	`LOAN_LOSS_PROVISION`
10	Other Current Asset	Other Current Assets	Guarantee Receivable	`GUARANTEE_RECEIVABLE`
11	Other Current Asset	Other Current Assets	Deferred Integral Loan Fees	`DEFERRED_INTEGRAL_FEES`
12	Other Current Liability	Other Current Liabilities	Guarantee Liability	`GUARANTEE_LIABILITY`
13	Other Current Asset	Other Current Assets	Repossessed Assets	`REPOSSESSED_ASSETS`
14	Income	Other Primary Income	Collateral Recovery	`COLLATERAL_RECOVERY`
15	Other Current Liability	Other Current Liabilities	Surplus Proceeds Payable	`SURPLUS_PROCEEDS_PAYABLE`
16	Expense	Other Business Expense	Income Tax Expense	`INCOME_TAX_EXPENSE`
17	Other Current Liability	Other Current Liabilities	Tax Payable	`TAX_PAYABLE`
18	Other Current Asset	Other Current Assets	Deferred Tax Asset	`DEFERRED_TAX_ASSET`
19	Other Current Liability	Other Current Liabilities	Deferred Tax Liability	`DEFERRED_TAX_LIABILITY`

Note on LOAN_LOSS_PROVISION: This is a contra-asset (allowance), not an expense. It reduces the net loans receivable on the balance sheet. The expense for measuring the allowance (IMPAIRMENT_LOSS_EXPENSE) is a separate account reserved for future use when ECL provisioning is automated.

Note on COLLATERAL_RECOVERY: This account captures both gains and losses on collateral disposal. When sale proceeds exceed the outstanding balance, the surplus is credited here (gain). When proceeds are less, the deficiency is debited here (loss).

Note on Detail Types: The exact detail type names depend on your QuickBooks region/company setup. The Account Type is what matters for financial statement classification; detail type is for additional categorization.

Account Mapping

The mapping table links internal account codes to QuickBooks accounts. The system resolves mappings with the following priority:

Per-Product + Per-Jurisdiction (most specific)
Per-Product only
Per-Jurisdiction only
Global (default for all products and jurisdictions)

Mapping Dimensions

Each mapping can be scoped by:

product_id — Optional, maps only for a specific product
fee_type — Optional, maps only for a specific fee type (e.g., ORIGINATION vs. INSURANCE)
jurisdiction_id — Optional, maps only for a specific jurisdiction

If a scoped mapping is not found, the system falls back to the global mapping.

Example: Fee-Specific Mapping

You may want different QuickBooks income accounts for different fee types:

Internal Code	Fee Type	QuickBooks Account
`FEE_INCOME`	(global)	Fee Income
`FEE_INCOME`	ORIGINATION	Origination Fee Income
`FEE_INCOME`	INSURANCE	Insurance Commission Income
`FEE_INCOME`	PROCESSING	Processing Fee Income

This gives you granular income tracking per fee type in QuickBooks.

Journal Entry Reference

The system posts these journal entries to QuickBooks. Each entry is a balanced double-entry with at least one debit and one credit line.

1. Loan Disbursement

When a loan is disbursed to a borrower:

Account	DR	CR
Loans Receivable	Principal
Cash / Bank		Principal

Description: "Loan disbursement - [loan number]" Posting: Immediate

2. Payment Received

When a borrower makes a repayment:

Account	DR	CR
Cash / Bank	Total payment
Loans Receivable		Principal portion
Interest Receivable		Interest portion
Fees Receivable		Fee portion
Penalties Receivable		Penalty portion

Key point: Payments credit the receivable accounts, not income accounts. Income was already recognized when the fee/interest was assessed or accrued. This prevents double-counting revenue.

Description: "Payment received - [payment reference]" Posting: Immediate

3. Interest Accrued

When interest accrues on a loan (daily or monthly):

Account	DR	CR
Interest Receivable	Accrual amount
Interest Income		Accrual amount

Description: "Interest accrual - Loan [loan ID]" Posting: Batch (aggregated daily)

4. Fee Assessed

When a fee is charged to a loan:

Standard fee (service fee):

Account	DR	CR
Fees Receivable	Fee amount
Fee Income		Fee amount

Integral fee (part of effective interest rate):

Account	DR	CR
Fees Receivable	Fee amount
Deferred Integral Loan Fees		Fee amount

The system determines which treatment to use based on the fee accounting policy. Origination fees that are integral to the loan's EIR are deferred and amortised over the loan life, not recognized as immediate income.

Description: "Fee assessed - [fee type] - Loan [loan ID]" Posting: Batch (aggregated per fee type)

5. Penalty Assessed

When a penalty is charged:

Account	DR	CR
Penalties Receivable	Penalty amount
Penalty Income		Penalty amount

Description: "Penalty assessed - [penalty type] - Loan [loan ID]" Posting: Batch (aggregated daily)

6. Loan Written Off

When a loan is written off as bad debt:

Account	DR	CR
Allowance for Expected Credit Losses	Write-off amount
Loans Receivable		Write-off amount

This removes the loan from the balance sheet using the contra-asset allowance. The expense for building the allowance (IMPAIRMENT_LOSS_EXPENSE) is recognized separately when the ECL is measured, not at write-off time.

Description: "Loan write-off - [loan number]" Posting: Immediate

7. Loan Closed

No journal entry is posted. Loan closure is an operational status change, not a financial event. The system explicitly skips journal entry creation for this event.

8. Guarantee Claimed

When a guarantee is invoked against a third-party guarantor:

Account	DR	CR
Guarantee Receivable	Claim amount
Loans Receivable		Claim amount

This transfers the borrower's loan exposure to a receivable from the guarantor. The lender is now owed by the guarantor, not the borrower. This is not an expense — it's a substitution of debtor.

Description: "Guarantee claimed - [reference]" Posting: Immediate

9. Collateral Liquidated

When collateral is sold and proceeds are applied directly to the loan:

Account	DR	CR
Cash / Bank	Liquidation amount
Loans Receivable		Liquidation amount

Pledged collateral remains off-balance-sheet until repossession. Sale proceeds are applied directly against the loan receivable.

Description: "Collateral proceeds applied - Loan [loan ID]" Posting: Immediate

10. Collateral Repossessed

When collateral is repossessed and transferred to lender control:

Account	DR	CR
Repossessed Assets	Outstanding balance
Loans Receivable		Outstanding balance

If the repossessed asset is subsequently sold:

Account	DR	CR
Cash / Bank	Sale proceeds
Repossessed Assets		Sale proceeds

If sale proceeds > outstanding balance (gain):

Account	DR	CR
Collateral Recovery	Surplus
Surplus Proceeds Payable		Surplus

If sale proceeds < outstanding balance (loss):

Account	DR	CR
Collateral Recovery	Deficiency
Repossessed Assets		Deficiency

Description: "Collateral repossession - Loan [loan ID]" Posting: Immediate

11. Surplus Proceeds Paid to Borrower

When surplus from collateral sale is paid to the borrower:

Account	DR	CR
Surplus Proceeds Payable	Surplus amount
Cash / Bank		Surplus amount

Description: "Surplus proceeds paid to borrower - Loan [loan ID]" Posting: Immediate

12. Guarantee Deposit Received

When cash collateral is received as a guarantee deposit:

Account	DR	CR
Cash / Bank	Deposit amount
Guarantee Liability		Deposit amount

The guarantee liability is recognised because the cash belongs to the guarantor and must be returned if the loan is repaid.

Description: "Cash collateral deposit - Guarantee [guarantee ID]" Posting: Immediate

13. Tax Provisioned

When income tax is provisioned for a reporting period:

Current tax:

Account	DR	CR
Income Tax Expense	Current tax
Tax Payable		Current tax

Deferred tax (expense):

Account	DR	CR
Income Tax Expense	Deferred tax
Deferred Tax Liability		Deferred tax

Deferred tax (benefit):

Account	DR	CR
Deferred Tax Asset	Deferred tax
Income Tax Expense		Deferred tax

Description: "Tax provision - [reporting period]" Posting: Immediate

Minimum Viable Setup

If you want to start simple, create just these 7 accounts in QuickBooks:

QB Account Type	Account Name	Internal Code	Covers
Bank	Operating Bank Account	`CASH`	Disbursements, payments, collateral proceeds
Other Current Asset	Loans Receivable	`LOANS_RECEIVABLE`	Principal tracking, write-offs, guarantee claims
Other Current Asset	Interest Receivable	`INTEREST_RECEIVABLE`	Interest accruals, interest collections
Other Current Asset	Fees Receivable	`FEES_RECEIVABLE`	Fee assessments, fee collections
Income	Interest Income	`INTEREST_INCOME`	Interest revenue
Income	Fee Income	`FEE_INCOME`	Fee revenue
Other Current Asset	Penalties Receivable	`PENALTIES_RECEIVABLE`	Penalty assessments, penalty collections

This covers the core loan lifecycle:

Loan disbursement
Payment receipt (principal + interest + fees + penalties)
Interest accrual
Fee assessment
Penalty assessment

Add the remaining accounts as you enable:

Penalty income tracking → Add Penalty Income
Write-offs (IFRS 9) → Add Allowance for Expected Credit Losses
Guarantee claims → Add Guarantee Receivable
Integral fee deferral → Add Deferred Integral Loan Fees
Guarantee deposits → Add Guarantee Liability
Collateral repossession → Add Repossessed Assets, Collateral Recovery, Surplus Proceeds Payable
Tax provisioning → Add Income Tax Expense, Tax Payable, Deferred Tax Asset, Deferred Tax Liability

Per-Product and Per-Jurisdiction Overrides

When to Use Overrides

Scenario	Override Type	Example
Different loan products need separate receivable accounts	Per-Product	Nano loans → "Nano Loans Receivable", Traditional → "Traditional Loans Receivable"
Different jurisdictions require separate income accounts	Per-Jurisdiction	Kenya interest income → "KES Interest Income", Zambia → "ZMW Interest Income"
Different fee types need separate income accounts	Per-Fee-Type	Origination → "Origination Fee Income", Insurance → "Insurance Commission"
A specific product in a specific jurisdiction needs its own account	Per-Product + Per-Jurisdiction	Nano loans in Kenya → "KE Nano Loans Receivable"

How to Create Overrides

Go to Accounting → Account Mappings
Click Add Mapping
Select the Internal Account Type
Optionally select a Product (leave blank for global)
Optionally select a Jurisdiction (leave blank for all)
Optionally enter a Fee Type (leave blank for all fee types)
Enter the QuickBooks Account ID
Click Save

The system will use the most specific mapping available. If no specific mapping is found, it falls back to the global mapping.

Posting Configuration

The system can post journal entries in two modes:

Mode	Events	Behavior
Immediate	Disbursement, Payment, Write-off, Guarantee Claim, Collateral Liquidation	Posts each event as it happens (real-time)
Batch	Interest Accrual, Fee Assessment, Penalty Assessment	Aggregates events and posts as a single entry (daily)

Batch Posting

For high-volume operations, batch posting reduces API calls to QuickBooks:

Interest accruals from 10,000 loans → 1 aggregated journal entry
Fee assessments across all loans → 1 aggregated entry per fee type
Penalty assessments across all loans → 1 aggregated entry

Configure batch posting in config/external_accounting.yaml:

external_accounting:
  enabled: false  # Set to true when ready
  provider: "quickbooks"
  posting_frequency: daily  # daily, weekly, monthly
  auto_post: true  # true = immediate, false = batch
  posting_time: "23:00"  # Batch posting time (HH:MM)

Troubleshooting

Common Issues

Issue	Cause	Fix
Journal entry fails with "no resolved external account mapping"	Missing account mapping for an internal code	Create the mapping in Account Mappings for the missing internal code
Journal entry fails with "account not found" in QuickBooks	Wrong QuickBooks Account ID in mapping	Verify the Account ID in QuickBooks and update the mapping
No entries posting to QuickBooks	Provider not activated or integration disabled	Activate the QuickBooks provider and set `enabled: true` in config
Entries posting to wrong account	Override mapping is too broad or too narrow	Check if product/jurisdiction-specific mappings are correct
Batch events not posting	No active accounting provider configured	Activate the QuickBooks provider in Admin → Accounting → Providers
Warning: "no active accounting providers configured"	Provider is inactive	This is expected if external accounting is not yet enabled. Events remain pending and will post when the provider is activated.

Checking Posting Status

Go to Accounting → Event Log to see all accounting events
Check the Status column: PENDING, PROCESSING, POSTED, FAILED, RETRYING
For failed events, check the Error column for details
Failed events are automatically retried up to 3 times with 5-minute intervals

Quick Setup Checklist

Create core accounts in QuickBooks (7 minimum)
Create extended accounts in QuickBooks (4 more for full lifecycle)
Create collateral & guarantee accounts in QuickBooks (4 more for collateral liquidation)
Create tax accounts in QuickBooks (4 more for tax provisioning)
Note QuickBooks Account IDs from Chart of Accounts
Enable QuickBooks provider in Hiana Loans Admin
Configure credentials (Client ID, Secret, Refresh Token, Company ID)
Activate provider (set to active)
Create global account mappings (map each internal code to QB Account ID)
Create per-product overrides (if needed for different loan products)
Create per-jurisdiction overrides (if operating in multiple countries)
Create per-fee-type overrides (if tracking fee income separately)
Test connection (Admin → Accounting → Providers → Test Connection)
Test with a small loan disbursement and verify the entry appears in QuickBooks
Enable external accounting in config (enabled: true)

Loan Servicing Operations Guide

Staff Onboarding & Invitations Guide