Understanding the Audit Trail

The audit trail is an immutable record of every significant action taken on the platform -- by the system, by investors, and by admins. It's your primary tool for understanding what happened, when, and why.

What Gets Recorded

Every audit entry includes:

• Action -- what happened (e.g. payment_failed, retry_scheduled, nsf_failure, investment_adjusted)
• Subject -- the primary record this action relates to (e.g. a specific Payment Order, Investment, or Identity)
• Related -- an additional related record for cross-referencing (e.g. the Investment related to a Payment Order action)
• Category -- the area of the system (e.g. payments, compliance, investments)
• Description -- a human-readable description of what happened
• Metadata -- structured data with details (IDs, counts, amounts, failure codes)
• Timestamp -- exactly when it happened

Where to Find the Audit Trail

In the admin panel, audit entries are accessible in several ways:

1. On the record itself -- each investment, payment order, and identity has audit entries shown on its detail page
2. Global audit log -- a searchable list of all audit entries across the platform
3. Filtered by category -- you can filter by payments, compliance, investments, etc.

Common Investigation Patterns

"Why is this investment stuck in Committed?"

1. Find the investment in admin
2. Check the audit trail for the most recent entries
3. Look for readiness evaluation results -- they'll tell you what the system determined (e.g. "awaiting KYC," "bank not registered")
4. Check the current status of the blocking item (identity, bank account, etc.)

"What happened with this payment?"

1. Find the payment order in admin
2. Check the audit trail chronologically:
   • When was it created?
   • When was it submitted to the provider?
   • Did it fail? What was the failure code?
   • Were retries scheduled? How many?
   • Did retries succeed or exhaust?
3. The metadata fields contain failure codes and retry counts

"Why did this investor get a failure email?"

1. Find the investment
2. Check the audit trail for payment_failed, nsf_failure, or payment_returned entries
3. The description explains the failure
4. Check for retry_scheduled entries to see if retries were attempted
5. Check for retry_exhausted if all retries failed

"Who made this adjustment?"

1. Find the investment
2. Check the audit trail for adjustment-related entries
3. The entry includes who made the change and the old/new values
4. Metadata may include the reason for the adjustment

"When was this funding close settled?"

1. Find the funding close in admin
2. Check the "Settled At" timestamp and "Settled By" admin
3. The audit trail shows the settlement event with the total amount and investor count

Reading Audit Entries

Understanding the Description

Descriptions are written to be human-readable. Examples:

• "ACH debit failed: insufficient funds. Retry 2/3 scheduled for 2026-02-14."
• "Payment permanently failed (account_closed). Not retriable. Admin action required."
• "Payment retries exhausted (3/3 attempts for insufficient_funds). Admin action required."
• "KYC verification submitted for Person #1234"

Understanding the Metadata

Metadata provides structured details. Common fields:

Tips for Using the Audit Trail

1. Read chronologically -- audit entries make the most sense when read in order. Start from the earliest entry and work forward.
2. Cross-reference related records -- if an audit entry on a Payment Order mentions an Investment, check the Investment's audit trail too for the full picture.
3. Look for patterns -- multiple retry_scheduled entries followed by retry_exhausted tells a clear story.
4. Use the category filter -- if you're investigating a payment issue, filter by the payments category to cut through noise.
5. Metadata is your detail layer -- when the description gives you the overview, the metadata gives you the specifics (exact failure codes, amounts, IDs).

What Admins Should Know

• The audit trail is immutable -- entries cannot be edited or deleted. This is intentional for compliance and accountability.
• Every significant action is recorded -- if something happened on the platform, there's an audit entry for it.
• Admin actions are tracked too -- when you make an adjustment, cancel an investment, or settle a funding close, your action is recorded with your identity.
• Use it before taking action -- always check the audit trail before intervening. The system may have already handled the situation, or there may be important context you'd miss otherwise.